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

パイプライン実行ポリシーは、プロジェクトのパイプラインでカスタムCI/CDジョブを強制的に実行します。スケジュールされたパイプライン実行ポリシーを使用すると、この強制実行を拡張し、定期的なケイデンス（毎日、毎週、または毎月）でCI/CDジョブを実行できます。これにより、新しいコミットがない場合でも、コンプライアンススクリプト、セキュリティスキャン、またはその他のカスタムCI/CDジョブを確実に実行できます。

パイプライン実行ポリシーをスケジュールする

既存のパイプラインにジョブを挿入したり、既存のジョブをオーバーライドしたりする通常のパイプライン実行ポリシーとは異なり、スケジュールされたポリシーは、定義したスケジュールに従って独立して実行される新しいパイプラインを作成します。スケジュールされたパイプラインは、プロジェクトの.gitlab-ci.ymlとは別のものであり、プロジェクトのCI/CDジョブは実行しません。

一般的なユースケースは次のとおりです:

• コンプライアンス要件を満たすため、定期的なケイデンスでセキュリティスキャンを強制実行する。
• プロジェクト設定を定期的にチェックする。
• 非アクティブなリポジトリに対して依存関係スキャンを実行し、新たに発見された脆弱性を検出する。
• コンプライアンスレポート用スクリプトをスケジュールに従って実行する。

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

スケジュールされたパイプライン実行ポリシーをすべてのプロジェクトで有効にする前に、テストを実行して、パイプラインが正常に動作することを確認し、ポリシーがインフラストラクチャに与える影響を把握できます。テスト実行では実際のパイプラインが実行されるため、タイミングやリソース使用量を正確に見積もることができます。

テストを実行するには:

1. 左側のサイドバーで、セキュリティ > ポリシーを選択します。
2. テストするスケジュールされたパイプライン実行ポリシーを選択します。
3. テスト実行タブを選択します。
4. グループレベルでポリシーを表示している場合は、ドロップダウンリストからターゲットプロジェクトを選択します。
5. テスト実行を開始するを選択します。

テスト実行では、ポリシーのCI/CD設定を使用して、選択したプロジェクトにパイプラインが作成されます。テスト実行タブで、テスト実行のステータスを監視できます。

テスト実行が完了すると、テスト実行タブに、実行時間やエラーメッセージを含む結果が表示されます。

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

スケジュールされたパイプライン実行ポリシーを設定するには、セキュリティポリシープロジェクトの.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つのセキュリティポリシープロジェクトには、スケジュールされたパイプライン実行ポリシーを最大5個含めることができます。
• 1つのスケジュールされたポリシーに設定できるスケジュールは、一度に1つのみです。
• 1つのスケジュールされたポリシーでは、最大5個のブランチをターゲットにできます。branchesを省略した場合、ポリシーはプロジェクトのデフォルトブランチでのみ実行されます。
• 複数のプロジェクトにポリシーを適用する場合は、利用可能なRunnerの処理能力に基づき、プロジェクト数に対応できる十分な長さの時間枠を指定してください。たとえば、1時間の時間枠を指定して1000のプロジェクトにポリシーを適用すると、その1時間全体にパイプラインの作成が均等に分散されます（1分あたり約16個のパイプライン）。Runnerがこのパイプライン作成レートを処理できることを確認するか、キューイングや遅延を避けるため、より長い時間枠を指定してください。
• 月次スケジュールでは、時間枠内でランダムに分散されるため、連続する実行の間隔が変動する場合があります。たとえば、ある月次スケジュールでは、前回の実行から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値に過去の日付を設定します。

CI/CD変数へのアクセスを制御します

デフォルトでは、スケジュールされたパイプライン実行ポリシーのジョブは、プロジェクトまたはグループのCI/CD変数にアクセスできません。このセキュアなデフォルト設定により、ポリシーが機密性の高いプロジェクト設定を意図せず公開することを防ぎます。

ポリシージョブがプロジェクトおよびグループの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つの個別のパイプライン（ブランチごとに1つ）が作成されます。

前提条件

スケジュールされたパイプライン実行ポリシーを使用するには、プロジェクトが次の要件を満たしている必要があります:

• CI/CD設定ファイルが、次のいずれかの場所に保存されていること:
  • セキュリティポリシープロジェクト
  • 公開プロジェクト
  • アクセスが有効になっている非公開プロジェクト（CI/CD設定ファイルへのアクセスを有効にするを参照）
• CI/CD設定ファイルに、スケジュールされたパイプラインに適したワークフロールールが含まれていること。

CI/CD設定ファイルへのアクセスを有効にする

ポリシーでCI/CD設定ファイルを参照する場合、セキュリティポリシーボットがそれらのファイルにアクセスできる必要があります。公開プロジェクト内のファイルには、デフォルトでアクセスできます。セキュリティポリシープロジェクトまたはその他の非公開プロジェクト内のファイルについては、次のいずれかのオプションを使用してアクセスを有効にします。

オプション1: セキュリティポリシープロジェクト内のファイルへのアクセスを許可する

CI/CD設定ファイルがセキュリティポリシープロジェクト自体に保存されている場合は、このオプションを使用します。この設定は、パイプライン実行ポリシーが挿入されたパイプラインをトリガーするすべてのユーザーに適用されます。

1. セキュリティポリシープロジェクトの左側のサイドバーで、設定 > 一般を選択します。
2. 可視性、プロジェクトの機能、権限を展開します。
3. CI/CD設定へのセキュリティポリシープロジェクトのアクセスを許可をオンにします。
4. 変更を保存を選択します。

オプション2: プライベートまたは内部プロジェクトへのアクセスを許可します

ポリシーのinclude:値で、セキュリティポリシープロジェクト以外の非公開または内部プロジェクトに保存されているCI/CD設定ファイルを参照する場合は、このオプションを使用します。

1. CI/CDファイルが保存されている非公開または内部プロジェクトにおいて、左側のサイドバーで、設定 > 一般を選択します。

2. 可視性、プロジェクトの機能、権限を展開します。

3. パイプライン実行ポリシーで、Allow access to CI/CD configuration files in this projectを選択します。

4. 許可するファイルパターンで、アクセスできるファイルを指定するために1つ以上のglobパターンをカンマで区切って追加します。

5. オプション。許可されたグループで、そのグループ内のプロジェクトのユーザーのみがCI/CD設定ファイルにアクセスできるようにするグループを選択します。

   指定されていない場合、ルート祖先グループ内の任意のプロジェクトのユーザーがファイルにアクセスできます。

6. 変更を保存を選択します。

許可されるファイルの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のように、複数のパターンをカンマで区切って指定します。

セキュリティポリシーボットユーザー

スケジュールされたパイプラインは、セキュリティポリシーボットユーザーによって実行されます。セキュリティポリシーボットユーザーは、セキュリティポリシーが適用される各プロジェクトに対して、GitLabが自動的に作成する専用のシステムアカウントです。ポリシーの実行を分離された安全な状態に保つため、ボットユーザーには次のセキュリティ制限があります:

• ボットユーザーは、該当する特定のプロジェクトにのみ属します。グループや他のプロジェクトに追加することはできません。
• ボットユーザーは外部ユーザーとして扱われ、デフォルトでは内部プロジェクトにアクセスできません。
• ボットユーザーは、セキュリティポリシープロジェクトおよび公開プロジェクト内のファイルにアクセスできます。
• ボットユーザーは、それらのプロジェクトが明示的にパイプライン実行ポリシー設定を有効にし、ファイルパスがプロジェクトで指定されたパターンと一致する場合にのみ、プライベートまたは内部プロジェクト内のファイルにアクセスできます。

ボットユーザーは他のプロジェクトのメンバーではないため、次のいずれのアクションも実行できません:

• アクセスを許可しない、または許可されるファイルパターンと一致しないプライベートまたは内部プロジェクトからCI/CD設定ファイルにアクセスします。
• 非公開または内部プロジェクトをターゲットとするマルチプロジェクト子パイプラインを開始する。
• 非公開または内部プロジェクトのアーティファクトやリソースにアクセスする。

スケジュールの制限

スケジュールされたパイプライン実行ポリシーを作成する際は、次の制限に注意してください:

• セキュリティポリシープロジェクトごとに作成できるスケジュールされたパイプライン実行ポリシーは、1つのスケジュールを持つ1つのポリシーに制限されます。
• スケジュールの最大頻度は1日1回（日次）です。
• ブランチを指定しない場合、スケジュールされたパイプライン実行ポリシーはデフォルトブランチでのみ実行されます。
• branches配列には、一意のブランチ名を最大5個指定できます。
• パイプラインを十分に分散させるため、時間枠は10分（600秒）以上にする必要があります。
• 利用可能なRunnerが不足している場合、スケジュールされたパイプラインが遅延することがあります。

トラブルシューティング

最初のスケジュールされた実行が遅れる場合があります

スケジュールされたパイプライン実行ポリシーを作成または更新すると、バックグラウンドワーカーがスケジュールレコードを非同期で作成します。バックグラウンドワーカーキューで遅延が発生した場合（例えば、高いシステム負荷のため）、バックグラウンドワーカーは、意図された最初の実行時刻が過ぎた後にスケジュールレコードを作成する可能性があります。この場合、最初の実行は即時ではなく、次にスケジュールされたタイミングで発生します。

例えば、午後2時に午後6時の実行のためにポリシーを作成し、バックグラウンドワーカーが午後7時までポリシーを処理しない場合、最初の実行は翌日の午後6時（またはスケジュール設定に基づく次の該当する日）にスケジュールされます。

この動作を回避するには:

• 意図された最初の実行時刻よりも十分に早くポリシーを作成します。
• test run featureを使用して、最初のスケジュールされた実行の前にポリシーが正しく機能することを確認してください。

スケジュールされたパイプラインが実行されない

スケジュールされたパイプラインが想定どおりに実行されない場合は、次のトラブルシューティング手順を実行します:

1. ポリシーのアクセス権を確認する: 次の点を確認します。
   • セキュリティポリシープロジェクト、公開プロジェクト、またはボットのアクセスが有効で、ファイルパターンが一致する非公開または内部プロジェクトに、CI/CD設定ファイルがあること。
   • セキュリティポリシープロジェクトでパイプライン実行ポリシー設定が有効になっていること（設定 > 一般 > 可視性、プロジェクトの機能、権限）。
2. CI設定を検証する:
   • 指定されたパスにCI/CD設定ファイルが存在することを確認します。
   • 手動パイプラインを実行して、設定が有効であることを確認します。
   • 設定に、スケジュールされたパイプラインに適したワークフロールールが含まれていることを確認します。
3. ポリシー設定を確認する:
   • ポリシーが有効になっていること（enabled: true）を確認します。
   • スケジュール設定の形式が正しく、指定した値が有効であることを確認します。
   • ブランチを指定している場合は、そのブランチがプロジェクトに存在することを確認します。
   • タイムゾーンの設定が正しいことを確認します（指定している場合）。
4. ログとアクティビティを確認する:
   • セキュリティポリシープロジェクトのCI/CDパイプラインログで、エラーがないか確認します。
5. Runnerの可用性を確認する:
   • Runnerが利用可能で、適切に設定されていることを確認します。
   • Runnerに、スケジュールされたジョブを処理できるだけのキャパシティがあることを確認します。