Scheduled pipeline execution policies

{{< details >}}

• Tier: Ultimate
• Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

{{< history >}}

• Introduced as an experiment in GitLab 18.0 with a flag named scheduled_pipeline_execution_policy_type defined in the policy.yml file.
• Changed to beta in GitLab 18.2.
• Generally available in GitLab 19.2.

{{< /history >}}

Pipeline execution policies enforce custom CI/CD jobs in your projects' pipelines. With scheduled pipeline execution policies, you can extend this enforcement to run the CI/CD job on a regular cadence (daily, weekly, or monthly), ensuring that compliance scripts, security scans, or other custom CI/CD job are executed even when there are no new commits.

Scheduling your pipeline execution policies

Unlike regular pipeline execution policies that inject or override jobs in existing pipelines, scheduled policies create new pipelines that run independently on the schedule you define. Scheduled pipelines are separate from your project's .gitlab-ci.yml and do not execute any of the project's CI/CD jobs.

Common use cases include:

• Enforce security scans on a regular cadence to meet compliance requirements.
• Check project configurations periodically.
• Run dependency scans on inactive repositories to detect newly discovered vulnerabilities.
• Execute compliance reporting scripts on a schedule.

Test a scheduled pipeline execution policy

Before enabling a scheduled pipeline execution policy across all projects, you can run a test to verify that the pipeline works and to understand how the policy impacts your infrastructure. The test run executes real pipelines to provide accurate timing and resource estimates.

[!note] Test runs create real pipelines and consume compute minutes against the target project.

To run a test:

1. In the left sidebar, select Security > Policies.
2. Select the scheduled pipeline execution policy you want to test.
3. Select the Test runs tab.
4. If you are viewing the policy at the group level, select a target project from the dropdown list.
5. Select Begin test run.

The test run creates a pipeline on the selected project using the policy's CI/CD configuration. You can monitor the test run status in the Test runs tab.

After the test run completes, the Test runs tab displays the result, including the duration and any error messages.

Configure schedule pipeline execution policies

To configure a scheduled pipeline execution policy, add additional configuration fields to the pipeline_execution_schedule_policy section of your security policy project's .gitlab/security-policies/policy.yml file:

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

Schedule configuration schema

The schedules section allows you to configure when security policy jobs run automatically. You can create daily, weekly, or monthly schedules with specific execution times and distribution windows.

Schedules configuration options

The schedules section supports the following options:

Schedule examples

Use daily, weekly, or monthly schedules.

Daily schedule example

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

Weekly schedule example

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

Monthly schedule example

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

Time window distribution

To prevent overwhelming your CI/CD infrastructure when applying policies to multiple projects, scheduled pipeline execution policies distribute the creation of the pipelines across a time window with some common rules:

• All pipelines are scheduled at random. Pipelines are randomly distributed during the specified time window.
• The minimum time window is 10 minutes (600 seconds), and the maximum is approximately 1 month (2,629,746 seconds).
• For monthly schedules, if you specify dates that don't exist in certain months (like 31 for February), those runs are skipped.
• A security policy project can contain up to five scheduled pipeline execution policies.
• A scheduled policy can only have one schedule configuration at a time.
• A scheduled policy can target up to five branches. If you omit branches, the policy runs on the project default branch only.
• When you apply a policy to multiple projects, ensure your time window is large enough to accommodate the number of projects, based on your available runner capacity. For example, a policy applied to 1000 projects with a one hour time window distributes pipeline creation evenly throughout that hour (approximately 16 pipelines per minute). Verify that your runners can handle this pipeline creation rate or choose a larger time window to avoid queuing or delays.
• For monthly schedules, the interval between consecutive runs may vary due to random distribution during the time window. For example, a monthly schedule might run 20 days after the previous run, then 30 days later. This distribution is the expected behavior because it helps distribute load across your infrastructure.

Snooze scheduled pipeline execution policies

You can temporarily pause scheduled pipeline execution policies using the snooze feature. Use the snooze feature during maintenance windows, holidays, or when you need to prevent scheduled pipelines from running for a specific time period.

How snoozing works

When you snooze a scheduled pipeline execution policy:

• No new scheduled pipelines are created during the snooze period.
• Pipelines that were created before the snooze continue to execute.
• The policy remains enabled but in a snoozed state.
• After the snooze period expires, scheduled pipeline execution resumes automatically.

Configuring snooze

To snooze a scheduled pipeline execution policy, add a snooze section to the schedule configuration:

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"

The snooze.until parameter specifies when the snooze period ends using the ISO8601 format: YYYY-MM-DDThh:mm:ss+00:00 where:

• YYYY-MM-DD: Year, month, and day
• T: Separator between date and time
• hh:mm:ss: Hours, minutes, and seconds in 24-hour format
• +00:00: Time zone offset from UTC (or Z for UTC)

For example, 2025-06-26T16:27:00+00:00 represents June 26, 2025, at 4:27 PM UTC.

Removing a snooze

To remove a snooze before its expiration time, remove the snooze section from the policy configuration or set a date in the past for the until value.

Control access to CI/CD variables

By default, scheduled pipeline execution policy jobs cannot access project or group CI/CD variables. This secure default prevents policies from unintentionally exposing sensitive project configuration.

To allow policy jobs to access project and group CI/CD variables, add the variables_override option to your policy configuration:

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 configuration options

variables_override examples

Block all project variables except specific ones:

variables_override:
  allowed: false
  exceptions:
    - DEPLOY_TOKEN
    - API_KEY

Allow all project variables except sensitive ones:

variables_override:
  allowed: true
  exceptions:
    - SECRET_KEY
    - PRIVATE_TOKEN

Schedule pipelines for specific branches

By default, schedules run on the default branch only. Scheduled pipeline execution policies support branch filtering, which allows you to schedule pipelines for additional branches. Use the branches property to perform regular scans or checks on other important branches in your project.

When you configure the branches property in your schedule:

• If you don't specify any branches, the scheduled pipeline runs only on the default branch.
• If you specify branches, the policy schedules pipelines for each specified branch that actually exists in the project.
• You can specify a maximum of five unique branch names per schedule.
• You must specify each branch name in full. Wildcard matching is not supported.

Branch filtering example

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

In this example, if all of the specified branches exist in the project, the policy creates four separate pipelines (one for each branch).

Prerequisites

To use scheduled pipeline execution policies, your project must meet the following requirements:

• Your CI/CD configuration file is stored in one of the following locations:
  • Your security policy project
  • A public project
  • A private project with access enabled (see Enable access to CI/CD configuration files)
• Your CI/CD configuration file must include appropriate workflow rules for scheduled pipelines.

Enable access to CI/CD configuration files

When your policy references CI/CD configuration files, the Security Policy Bot must have access to them. Files in public projects are accessible by default. For files in your security policy project or other private projects, enable access using one of the following options.

Option 1: Grant access to files in the security policy project

If your CI/CD configuration files are stored in the security policy project itself, use this option. This setting applies to any user who triggers a pipeline with pipeline execution policies injected.

1. In your security policy project, in the left sidebar, select Settings > General.
2. Expand Visibility, project features, permissions.
3. Turn on Grant security policy project access to CI/CD configuration.
4. Select Save changes.

Option 2: Allow access to private or internal projects

If your policy include: value references a CI/CD configuration file stored in a private or internal project other than the security policy project, use this option.

1. In the private or internal project that stores CI/CD files, in the left sidebar, select Settings > General.

2. Expand Visibility, project features, permissions.

3. In Pipeline execution policies, select Allow access to CI/CD configuration files in this project.

4. In Allowed file patterns, add one or more glob patterns to specify the files that can be accessed, separated by commas.

5. Optional. In Allowed group, select a group to allow only users from projects in that group to access CI/CD configuration files.

   If not specified, users from any project in the root ancestor group can access the files.

6. Select Save changes.

The glob patterns for the allowed files must match the paths specified in the include:file: value. For example:

• For include:file: ci/security-scan.yml, use ci/**/*.yml or ci/security-scan.yml.
• For include:file: policy-ci.yml, use *.yml or policy-ci.yml.
• For multiple directories, use multiple patterns, separated by commas, like ci/**/*.yml, templates/**/*.yml.

Security Policy Bot User

Scheduled pipelines are executed by the Security Policy Bot User, a dedicated system account that GitLab automatically creates for each project the security policy applies to. To ensure that policy execution remains isolated and secure, the bot user has the following security restrictions:

• The bot user is a member of that specific project only. It cannot be added to groups or other projects.
• The bot user is treated as an external user and cannot access internal projects by default.
• The bot user can access files in the security policy project and public projects.
• The bot user can access files in private or internal projects only if those projects explicitly enable the Pipeline execution policies setting and the file path matches the pattern specified in the project.

Because the bot user is not a member of other projects, it cannot complete any of the following actions:

• Access CI/CD configuration files from private or internal projects that do not allow access or do not match allowed file patterns.
• Start multi-project child pipelines that target private or internal projects.
• Access artifacts or resources from private or internal projects.

[!important] When you include files from a private or internal project, enable the Pipeline execution policies setting in that project and set matching file patterns. Without these settings, pipeline execution fails with an access error.

Scheduling limits

Be aware of the following limits when creating scheduled pipeline execution policies:

• The maximum number of scheduled pipeline execution policies per security policy project is limited to one policy with one schedule.
• The maximum frequency for schedules is once per day (daily).
• If no branches are specified, scheduled pipeline execution policies run only on the default branch.
• You can specify up to five unique branch names in the branches array.
• Time windows must be at least 10 minutes (600 seconds) to ensure sufficient distribution of pipelines.
• Scheduled pipelines can be delayed if there are insufficient runners available.

Troubleshooting

First scheduled run may be delayed

When you create or update a scheduled pipeline execution policy, a background worker creates the schedule record asynchronously. If the background worker queue experiences delays (for example, due to high system load), the background worker might create the schedule record after the intended first run time passes. In this case, the first run occurs at the next scheduled occurrence instead of immediately.

For example, if you create a policy at 2:00 PM for a 6:00 PM run, but the background worker doesn't process the policy until 7:00 PM, the first run is scheduled for 6:00 PM the following day (or the next applicable day based on your schedule configuration).

To work around this behavior:

• Create policies well in advance of the intended first run time.
• Use the test run feature to verify the policy works correctly before the first scheduled run.

Scheduled pipelines not running

If your scheduled pipelines are not running as expected, follow these troubleshooting steps:

1. Check policy access: Verify that:
   • The CI/CD configuration file is in the security policy project, in a public project, or in a private or internal project with bot access enabled and matching file patterns.
   • The Pipeline execution policies setting is enabled in the security policy project (Settings > General > Visibility, project features, permissions).
2. Validate CI configuration:
   • Check that the CI/CD configuration file exists at the specified path.
   • Verify the configuration is valid by running a manual pipeline.
   • Ensure the configuration includes appropriate workflow rules for scheduled pipelines.
3. Verify policy configuration:
   • Ensure the policy is enabled (enabled: true).
   • Verify that the schedule configuration has the correct format and valid values.
   • If you've specified branches, verify that the branches exist in the project.
   • Verify that the time zone setting is correct (if specified).
4. Review logs and activity:
   • Check the security policy project's CI/CD pipeline logs for any errors.
5. Check runner availability:
   • Ensure that runners are available and configured properly.
   • Verify that runners have the capacity to handle the scheduled jobs.