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 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 Help us learn about your current experience with the documentation. Take the survey . Policies * Tier : Ultimate * Offering : GitLab.com, GitLab Self-Managed, GitLab Dedicated Policies provide security and compliance teams with a way to enforce controls globally in their organization. Security teams can ensure: * Security scanners are enforced in development team pipelines with proper configuration. * All scan jobs execute without any changes or alterations. * Proper approvals are provided on merge requests, based on results from those findings. * Vulnerabilities that are no longer detected are resolved automatically, reducing the workload of triaging vulnerabilities. Compliance teams can enforce: * Multiple approvers on all merge requests * Projects settings based on organizational requirements, such as enabling or locking merge request settings or repository settings. The following policy types are available: * Scan execution policy . Enforce security scans, either as part of the pipeline or on a specified schedule. * Merge request approval policy . Enforce project-level settings and approval rules based on scan results. * Pipeline execution policy . Enforce CI/CD jobs as part of project pipelines. * Scheduled pipeline execution policy . Enforce custom CI/CD jobs on a scheduled cadence across projects, independent of commit activity. * Vulnerability management policy . Automatically resolve vulnerabilities that are no longer detected in the default branch. Configure the policy scope policy_scope keyword Use the policy_scope keyword to enforce the policy on only those groups, projects, compliance frameworks, security attributes, or a combination, that you specify. To scope a policy by security attributes, enable the security_attributes_policy_scope experiment in the .gitlab/security-policies/policy.yml file for your security policy project: experiments : security_attributes_policy_scope : enabled : true You can scope a policy by only the four built-in security attribute categories: business_impact , application , business_unit , and exposure . You can create custom attribute values in these categories and scope by those values, but you cannot scope by custom categories. The business_impact , application , business_unit , and exposure fields scope the policy by security attributes . Security attribute scoping applies to scan execution, merge request approval, pipeline execution, and vulnerability management policies. It does not apply to dependency firewall policies. Field Type Possible values Description match_mode string all , any Introduced in GitLab 18.10. Determines how the policy handles multiple scope conditions. Use all (default) to require that all conditions match, or any to require that at least one condition matches. compliance_frameworks array Not applicable List of IDs of the compliance frameworks in scope for enforcement, in an array of objects with key id . projects object including , excluding Use excluding: or including: then list the IDs of the projects you wish to include or exclude, in an array of objects with key id . You can also exclude projects by type using type: personal for personal projects or type: archived for archived projects. groups object including , excluding Use excluding: or including: then list the IDs of the groups you wish to include or exclude, in an array of objects with key id . Only groups linked to the same security policy project can be listed in the policy. business_impact object including , excluding Introduced in GitLab 18.11 with a flag named security_attributes_policy_scope flag. Enabled by default. List the IDs of the Business Impact security attribute values to include or exclude, in an array of objects with key id . application object including , excluding Introduced in GitLab 18.11 with a flag named security_attributes_policy_scope flag. Enabled by default. List the IDs of the Application security attribute values to include or exclude, in an array of objects with key id . business_unit object including , excluding Introduced in GitLab 18.11 with a flag named security_attributes_policy_scope flag. Enabled by default. List the IDs of the Business Unit security attribute values to include or exclude, in an array of objects with key id . exposure object including , excluding Introduced in GitLab 18.11 with a flag named security_attributes_policy_scope flag. Enabled by default. List the IDs of the Exposure security attribute values to include or exclude, in an array of objects with key id . Empty collections in policy_scope When a policy_scope field is set to an empty collection ( [] ), it is treated as if the field were omitted entirely. This means the policy applies to all projects without any restrictions. Specifically: * projects: { including: [] } applies the policy to all projects, not to zero projects. * groups: { including: [] } applies the policy to all groups, not to zero groups. * compliance_frameworks: [] applies the policy to all projects, not to projects with no framework. This behavior maintains backward compatibility with existing policies that rely on having empty collections being treated as if the filter was not provided. To prevent a policy from applying to any project, set enabled: false instead of using an empty collection: policy_scope : projects : including : - id : 123 enabled : false # Disables the policy entirely Understanding match_mode When you specify multiple scope conditions (for example, both projects and groups ), the match_mode field determines how these conditions are combined: * all (default) : The policy applies only to projects that match all of the specified conditions. This mode is more restrictive and maintains backward compatibility with existing policies. * any : The policy applies to projects that match any of the specified conditions. This mode is more permissive and useful when you want to target different sets of projects with a single policy. For example, if you specify both a list of including projects and a list of including groups: * With match_mode: all , a project must be in the projects list and belong to one of the specified groups. * With match_mode: any , a project is in scope if it s in the projects list or belongs to one of the specified groups. When you combine excluding and including conditions with match_mode: any , be aware that the excluding condition broadens the policy s reach. Because OR logic means the policy applies if any condition matches, an excluding groups condition (which matches all projects except those in the excluded groups) means the policy applies to most projects, regardless of what is specified in including conditions. For example, a policy that excludes group-2 from the groups list and includes specific projects group-1/project-1-1 and group-2/project-2-1 : policy_scope : match_mode : any groups : excluding : - id : 200 # group-2 projects : including : - id : 101 # group-1/project-1-1 - id : 201 # group-2/project-2-1 With this configuration, the policy applies not only to the two explicitly included projects, but also to all other projects outside group-2 (such as group-1/project-1-2 , which is not listed in the including projects). The excluding groups condition matches any project not in group-2 , and with OR logic, a single match is sufficient for the policy to apply. Scope examples In this example, the scan execution policy enforces a SAST scan in every release pipeline, on every project with the compliance frameworks with an ID either 2 or 11 applied to them. --- scan_execution_policy : - name : Enforce specified scans in every release pipeline description : This policy enforces a SAST scan for release branches enabled : true rules : - type : pipeline branches : - release/* actions : - scan : sast policy_scope : compliance_frameworks : - id : 2 - id : 11 In this example, the scan execution policy enforces a secret detection and SAST scan on pipelines for the default branch, on all projects in the group with ID 203 (including all descendent subgroups and their projects), excluding the project with ID 64 . - name : Enforce specified scans in every default branch pipeline description : This policy enforces secret detection and SAST scans for the default branch enabled : true rules : - type : pipeline branches : - main actions : - scan : secret_detection - scan : sast policy_scope : groups : including : - id : 203 projects : excluding : - id : 64 In this example, the scan execution policy enforces a SAST scan on all projects except archived projects. This is useful when you have many archived projects that should not be scanned. - name : Enforce SAST scan excluding archived projects description : This policy enforces SAST scans but excludes archived projects enabled : true rules : - type : pipeline branches : - main actions : - scan : sast policy_scope : projects : excluding : - type : archived In this example, the scan execution policy uses match_mode: any to enforce a secret detection scan on either specific high-priority projects or on all projects within specific groups. Without match_mode: any , a project must be in the projects list and in one of the specified groups for the policy to apply. - name : Enforce secret detection on priority projects or security groups description : This policy enforces secret detection on specific projects or all projects in security-focused groups enabled : true rules : - type : pipeline branches : - main actions : - scan : secret_detection policy_scope : match_mode : any projects : including : - id : 123 # High-priority project outside of security groups - id : 456 # Another critical project groups : including : - id : 78 # Security team's group - id : 90 # Compliance team's group In this example, the scan execution policy enforces a SAST scan on the default branch, on every project that has the Business Impact security attribute value with ID 5 (for example, Mission Critical ). Projects gain or lose this scope as the attribute is added or removed, with no change to the policy. - name : Enforce SAST on mission-critical projects description : This policy enforces a SAST scan on projects with a Business Impact security attribute enabled : true rules : - type : pipeline branches : - main actions : - scan : sast policy_scope : business_impact : including : - id : 5 Separation of duties Separation of duties is vital to successfully implementing policies. Implement policies that achieve the necessary compliance and security requirements, while allowing development teams to achieve their goals. Security and compliance teams: * Should be responsible for defining policies and working with development teams to ensure the policies meet their needs. Development teams: * Should not be able to disable, modify, or circumvent the policies in any way. To enforce a security policy project on a group, subgroup, or project, you must have either: * The Owner role in that group, subgroup, or project. * A custom role in that group, subgroup, or project with the manage_security_policy_link permission. The Owner role and custom roles with the manage_security_policy_link permission follow the standard hierarchy rules across groups, subgroups, and projects: Organization unit Group owner or group manage_security_policy_link permission Subgroup owner or subgroup manage_security_policy_link permission Project owner or project manage_security_policy_link permission Group No No Subgroup No Project Required permissions To create and manage security policies: * For policies enforced on groups: You must have the Maintainer or Owner role for the group. * For policies enforced on projects: * You must be the project owner. * You must be a group member with permissions to create projects in the group. If you re not a group member, you may face limitations in adding or editing policies for your project. The ability to create and manage policies requires permissions to create projects in the group. Make sure you have the required permissions in the group, even when working with project-level policies. Policy recommendations When implementing policies, consider the following recommendations. Branch names When specifying branch names in a policy, use a generic category of protected branches, such as default branch or all protected branches , not individual branch names. A policy is enforced on a project only if the specified branch exists in that project. For example, if your policy enforces rules on branch main , but some projects in scope are using production as their default branch, the policy is not applied for the latter. Push rules In GitLab 17.3 and earlier, if you use push rules to validate branch names ensure they allow creation of branches with the prefix update-policy- . This branch naming prefix is used when a security policy is created or amended. For example, update-policy-1659094451 , where 1659094451 is the timestamp. If push rules block the creation of the branch the following error occurs: Branch name `update-policy-<timestamp>` does not follow the pattern `<branch_name_regex>`. In GitLab 17.4 and later, security policy projects are excluded from push rules that enforce branch name validation. Security policy projects To prevent the exposure of sensitive information that was intended to remain private in your security policy project, when you link security policy projects to other projects: * Don t include sensitive content in your security policy projects. * Before linking a private security policy project, review the member list of the target project to ensure all members should have access to your policy content. * Evaluate the visibility settings of target projects. * Use security policy management audit logs to monitor project linking. These recommendations prevent sensitive information exposure for the following reasons: * Shared visibility: When a private security project is linked to another project, users with access to the Security Policies page of the linked project can view the contents of the .gitlab/security-policies/policy.yml file. This includes linking a private security policy project to a public project, which can expose the policy contents to anyone who can access the public project. * Access control: All members of the project to which a private security project is linked can view the policy file on the Policy page, even if they don t have access to the original private repository. Security and compliance controls Project maintainers can create policies for projects that interfere with the execution of policies for groups. To limit who can modify policies for groups and ensure that compliance requirements are being met, when you implement critical security or compliance controls: * Use custom roles to restrict who can create or modify pipeline execution policies at the project level. * Configure protected branches for the default branch in your security policy projects to prevent direct pushes. * Set up merge request approval rules in your security policy projects that require review from designated approvers. * Monitor and review all policy changes in policies for both groups and projects. Policy management The Policies page displays deployed policies for all available environments. You can check a policy s information (for example, description or enforcement status), and create and edit deployed policies: * In the top bar, select Search or go to and find your project. * In the left sidebar, select Secure > Policies . A green checkmark in the first column indicates that the policy is enabled and enforced on all groups and projects within its scope. A gray checkmark indicates that the policy is currently not enabled. Policy editor The policy editor has two modes: * Rule mode: Construct and preview policy rules using rule blocks and related controls. * YAML mode: Enter a policy definition in YAML format. Suitable for expert users and cases that the rule mode doesn t support. You can switch between rule mode and YAML mode at any time. If your YAML has errors or unsupported data, rule mode turns off automatically. Fix the YAML first to use rule mode again. Use the policy editor to create, edit, and delete policies: * In the top bar, select Search or go to and find your project. * In the left sidebar, select Secure > Policies . * To create a new policy, select New policy in the Policies page header, then select the policy type. * To edit an existing policy, select Edit policy in the selected policy drawer. * Select Configure with a merge request to save and apply the changes. The policy s YAML is validated and any resulting errors are displayed. * Review and merge the resulting merge request. If you are a project owner and a security policy project is not associated with this project, a security policy project is created and linked to this project when the merge request is created. GitLab sy