Scan execution policies | GitLab Docs Skip to main content Go to GitLab Docs homepage What's new? What's new? Get free trial Toggle menu * Use GitLab * GitLab Duo * GitLab Orbit * Extend * Install * Administer * Subscribe * Contribute * Solutions Getting started Tutorials Manage your organization Organize work with projects Plan and track work Manage authentication and authorization Use Git Manage your code Use CI/CD to build your application Secure your application Getting started Tutorials AI Governance Application security Compliance Detect Triage Analyze Remediate GitLab advisory database CVE ID requests Policies Enforcement Scan execution policies Tutorial: Set up a scan execution policy Merge request approval policies Pipeline execution policies Vulnerability management policies Security glossary Deploy and release your application Manage your infrastructure Monitor your application Analyze GitLab usage Release notes Feature support Find your GitLab version * GitLab Docs / * Use GitLab / * Secure your application / * Policies / * Scan execution policies Help us learn about your current experience with the documentation. Take the survey . Scan execution policies * Tier : Ultimate * Offering : GitLab.com, GitLab Self-Managed, GitLab Dedicated History * Overriding predefined variables in scan execution policies introduced in GitLab 16.10 with a feature flag named allow_restricted_variables_at_policy_level . Enabled by default. Feature flag allow_restricted_variables_at_policy_level removed in GitLab 17.5. Scan execution policies enforce GitLab security scans based on the default or latest security CI/CD templates . You can deploy scan execution policies as part of the pipeline or on a specified schedule. Scan execution policies enforce security scans across all projects that are linked to the security policy project. For projects without a .gitlab-ci.yml file, or projects where AutoDevOps is disabled, security policies create the .gitlab-ci.yml file implicitly. The .gitlab-ci.yml file ensures policies that run secret detection, static analysis, or other scanners that do not require a build in the project can always run and be enforced. Both scan execution policies and pipeline execution policies can configure GitLab security scans across multiple projects to manage security and compliance. Scan execution policies are faster to configure, but are not customizable. If any of the following cases are true, use pipeline execution policies instead: * You require advanced configuration settings. * You want to enforce custom CI/CD jobs or scripts. * You want to enable third-party security scans through an enforced CI/CD job. Create a scan execution policy To create a scan execution policy, you can use any of the following resources: * For a video walkthrough, see How to set up Security Scan Policies in GitLab . * Learn more about enforcing scan execution policies on projects with no GitLab CI/CD configuration . * For instructions on how to create scan execution policies, see tutorial: set up a scan execution policy Restrictions * You can assign a maximum of five rules to each policy. * You can assign a maximum of five scan execution policies to each security policy project. * Local project YAML files cannot override scan execution policies. Scan execution policies take precedence over any configurations defined for a pipeline, even if you use the same job name in your project s CI/CD configuration. * Scheduled policies ( type: schedule ) execute according to their scheduled cadence only. Updating a policy does not trigger an immediate scan. * Policy updates that you make directly to the YAML configuration files (with a commit or push instead of in the policy editor) can take up to 10 minutes to propagate through the system. (See issue 512615 for proposed changes to this limitation.) Job stages DAST scans always run in the dast stage. If the dast stage does not exist, then GitLab injects a dast stage at the end of the pipeline. Policy jobs for all other scans, run in the test stage of the pipeline. If you remove the test stage from the default pipeline, jobs run in the scan-policies stage instead according to these rules: * If the scan-policies stage doesn t already exist, GitLab injects the stage into the CI/CD pipeline at evaluation time. * If the build stage exists, GitLab injects scan-policies immediately after the build stage. * If the build stage does not exist, GitLab injects scan-policies at the beginning of the pipeline. To avoid job name conflicts, a hyphen and a number are appended to the job name. Each number is a unique value for each policy action. For example, secret-detection becomes secret-detection-1 . Scan execution policy editor History * Merge Request Security Template : * Introduced in GitLab 18.2 with a feature flag named flexible_scan_execution . Disabled by default. * Enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated in GitLab 18.3. * Generally available in GitLab 18.4. Feature flag flexible_scan_execution removed. Use the scan execution policy editor to create or edit a scan execution policy. Prerequisites: * By default, only group, subgroup, or project Owners have the permissions required to create or assign a security policy project. Alternatively, you can create a custom role with the permission to manage security policy links . When you create your first scan execution policies, choose from these templates for common use cases: * Merge Request Security * Use case: You want security scans to run only when merge requests are created, not on every commit. * When to use: For projects using merge request pipelines that need security scans to run on source branches targeting default or protected branches. * Best for: Aligning with merge request approval policies and reducing infrastructure costs by avoiding scans on every branch. * Pipeline sources: Primarily merge request pipelines. * Scheduled Scanning * Use case: You want security scans to run automatically on a schedule (like daily or weekly) regardless of code changes. * When to use: For security scanning on a regular cadence, independent of development activity. * Best for: Compliance requirements, baseline security monitoring, or projects with infrequent commits. * Pipeline sources: Scheduled pipelines. * Release Security * Use case: You want security scans to run on all changes to your main or release branches. * When to use: For projects that need comprehensive scanning before releases, or on protected branches. * Best for: Release-gated workflows, production deployments, or high-security environments. * Pipeline sources: Push pipelines to protected branches, release pipelines. If the available template do not meet your needs, or you require more customized scan execution policies, you can: * Select the Custom option and create your own scan execution policy with custom requirements. * Access more customizable options for security scan and CI enforcement using pipeline execution policies . Once your policy is complete, save the policy by selecting Configure with a merge request at the bottom of the editor. You are redirected to the merge request on the project s configured security policy project. If a security policy project is not linked to your project, GitLab automatically creates one. You can remove existing policies from the editor interface by selecting Delete policy at the bottom of the editor. This action creates a merge request to remove the policy from your policy.yml file. Most policy changes take effect as soon as the merge request is merged. Any changes committed directly to the default branch instead of a merge request require up to 10 minutes before the policy changes take effect. For DAST execution policies, the way you apply site and scanner profiles in the rule mode editor depends on where the policy is defined: * For policies in projects, in the rule mode editor, choose from a list of profiles that are already defined in the project. * For policies in groups, you must type in the names of the profiles to use. To prevent pipeline errors, profiles with matching names must exist in all of the group s projects. Scan execution policies schema A YAML configuration with scan execution policies consists of an array of objects matching the scan execution policy schema. Objects are nested under the scan_execution_policy key. You can configure a maximum of five policies under the scan_execution_policy key. Any other policies configured after the first five are not applied. When you save a new policy, GitLab validates the policy s contents against this JSON schema . If you re not familiar with JSON schemas , the following sections and tables provide an alternative. Field Type Required Possible values Description scan_execution_policy array of scan execution policy true List of scan execution policies (maximum 5) Scan execution policy schema History * Limit of actions per policy introduced in GitLab 17.4 with feature flags named scan_execution_policy_action_limit (for projects) and scan_execution_policy_action_limit_group (for groups). Disabled by default. * Limit of actions per policy generally available in GitLab 18.0. Feature flags scan_execution_policy_action_limit (for projects) and scan_execution_policy_action_limit_group (for groups) removed. Field Type Required Description name string true Name of the policy. Maximum of 255 characters. description string false Description of the policy. enabled boolean true Flag to enable ( true ) or disable ( false ) the policy. rules array of rules true List of rules that the policy applies. actions array of actions true List of actions that the policy enforces. Limited to a maximum of 10 in GitLab 18.0 and later. policy_scope object of policy_scope false Defines the scope of the policy based on the projects, groups, or compliance framework labels you specify. skip_ci object of skip_ci false Defines whether users can apply the skip-ci directive. no_pipeline object of no_pipeline false Defines whether users can apply the no_pipeline directive. skip_ci type History * Introduced in GitLab 17.9. Scan execution policies offer control over who can use the [skip ci] directive. You can specify certain users or service accounts that are allowed to use [skip ci] while still ensuring critical security and compliance checks are performed. Use the skip_ci keyword to specify whether users are allowed to apply the skip_ci directive to skip the pipelines. When the keyword is not specified, the skip_ci directive is ignored, preventing all users from bypassing the pipeline execution policies. Field Type Possible values Description allowed boolean true , false Flag to allow ( true ) or prevent ( false ) the use of the skip-ci directive for pipelines with enforced pipeline execution policies. allowlist object users Specify users who are always allowed to use skip-ci directive, regardless of the allowed flag. Use users: followed by an array of objects with id keys representing user IDs. Scan execution policies that have the rule type schedule always ignore the skip_ci option. Scheduled scans run at their configured times regardless of whether [skip ci] (or any of its variations) appear in the last commit message. This ensures that security scans occur on a predictable schedule even when CI/CD pipelines are otherwise skipped. no_pipeline type Scan execution policies offer control over who can use the [no_pipeline] directive. You can specify certain users or service accounts that are allowed to use [no_pipeline] while still ensuring critical security and compliance checks are performed. Use the no_pipeline keyword to specify whether users are allowed to apply the no_pipeline directive to not create pipeline on a push. When the keyword is not specified, the no_pipeline directive is ignored, preventing all users from bypassing the pipeline execution policies. Field Type Possible values Description allowed boolean true , false Flag to allow ( true ) or prevent ( false ) the use of the no_pipeline directive for pipelines with enforced pipeline execution policies. allowlist object users Specify users who are always allowed to use no_pipeline directive, regardless of the allowed flag. Use users: followed by an array of objects with id keys representing user IDs. Scan execution policies that have the rule type schedule always ignore the no_pipeline option. Scheduled scans run at their configured times regardless of whether [no_pipeline] (or any of its variations) appear in the last commit message. This ensures that security scans occur on a predictable schedule even when CI/CD pipelines are not created. pipeline rule type History * The pipeline_sources field and the branch_type options target_default and target_protected : * Introduced in GitLab 18.2 with a feature flag named flexible_scan_execution . * Enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated in GitLab 18.3. * Generally available in GitLab 18.4. Feature flag flexible_scan_execution removed. This rule enforces the defined actions whenever the pipeline runs for a selected branch. Field Type Required Possible values Description type string true pipeline The rule s type. branches 1 array of string true if branch_type field does not exist * or the branch s name The branch the given policy applies to (supports wildcard). For compatibility with merge request approval policies, you should target all branches to include the scans in the feature branch and default branch branch_type 1 string true if branches field does not exist default , protected , all , target_default 2 , or target_protected 2 The types of branches the given policy applies to. branch_exceptions array of string false Names of branches Branches to exclude from this rule. pipeline_sources 2 object false api , chat , external , external_pull_request_event , merge_request_event 3 , pipeline , push 3 , schedule , trigger , unknown , web An object with an including key set to an array of pipeline sources that determine when the scan execution job triggers. For more information, see CI_PIPELINE_SOURCE predefined variable . * You must specify either branches or branch_type , but not both. * Some options are only available with the flexible_scan_execution feature flag enabled. See the history for details. * When the branch_type options target_default or target_protected are specified, the pipeline_sources:including field supports only the merge_request_event and push fields. schedule rule type History * New scan_execution_pipeline_worker worker to scheduled scans to create pipelines: * Introduced in GitLab 16.11 with a feature flag . * Enabled on GitLab.com in GitLab 17.5. * Generally available in GitLab 17.6. Feature flag scan_execution_pipeline_worker removed. * New application setting security_policy_scheduled_scans_max_concurrency : * Introduced in GitLab 17.1. The concurrency limit applies when both the scan_execution_pipeline_worker and scan_execution_pipeline_concurrency_control are enabled. * Removed a new application setting security_policy_scheduled_scans_max_concurrency in GitLab 17.11. * Concurrency limit for scan execution scheduled jobs: * Introduced in GitLab 17.3 with a feature flag named scan_execution_pipeline_concurrency_control . * Generally available in GitLab 17.9. Feature flag scan_execution_pipeline_concurrency_control removed. Use the schedule rule type to run security scanners on a schedule. A scheduled pipeline: * Runs only the scanners defined in the policy, not the jobs defined in the project s .gitlab-ci.yml file. * Runs according to the schedule defined in the cadence field. * Runs under a security_policy_bot user account in the project, with the Guest role and permissions to create pipelines and read the repository s content from a CI/CD job. This account is created when the policy is linked to a group or project. * On GitLab.com, only the first 10 schedule rules in a scan execution policy are enforced. Rules that exceed the limit have no effect. Field Type Required Possible values Description type string true schedule The rule s type. branches 1 array of string true if either branch_type or agents fields does not exist * or the branch s name The branch the given policy applies to (supports wildcard). branch_type 1 string true if either branches or agents fields does not exist default , protected , or all The types of branches the given policy applies to. branch_exceptions array of string false Names of branches Branches to exclude from this rule. cadence string true Cron expression with limited options. For example, 0 0 * * * creates a schedule to run every day at midnight (12:00 AM). A whitespace-separated string containing five fields that represents the scheduled time. timezone string false Time zone identifier (for example, America/New_York ) Time zone to apply to the cadence. Value must be an IANA Time Zone Database identifier. time_window object false Distribution and duration settings for scheduled security scans. agents 1 object true if either branch_type or branches fields do not exist The name of the GitLab agents for Kubernetes where Operational container scanning runs. The object key is the name of the Kubernetes agent configured for your project in GitLab. * You must specify only one of branches , branch_type , or agents . Cadence Use the cadence field to schedule when you want the policy s actions to run. The cadence field uses cron syntax , but with some restrictions: * Only the following types of cron syntax are supported: * A daily cadence of once per hour around specified time, for example: 0 18 * * * * A weekly cadence of once per week on a specified day and around specified time, for example: 0 13 * * 0 * Use of the comma (,), hyphens (-), or step operators (/) are not supported for minutes and hours. Any scheduled pipeline using these char