Skip to content

Security policy projects

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

Security policy projects enforce policies across multiple projects. A security policy project is a special type of project used only to contain policies. To enforce the policies contained in a security policy project, link the security policy project to the projects, subgroups, or groups you want to enforce the policies on. A security policy project can contain multiple policies but they are enforced together. A security policy project enforced on a group or subgroup applies to everything below in the hierarchy, including all subgroups and their projects.

Policy changes made in a merge request take effect as soon as the merge request is merged. Those that do not go through a merge request, but instead are committed directly to the default branch, may require up to 10 minutes before the policy changes take effect.

Policies are stored in the .gitlab/security-policies/policy.yml YAML file.

Security policy project implementation

Implementation options for security policy projects differ slightly between GitLab.com, GitLab Dedicated, and GitLab Self-Managed. The main difference is that on GitLab.com it's only possible to create subgroups. Ensuring separation of duties requires more granular permission configuration.

Enforce policies globally in your GitLab.com namespace

  • Tier: Ultimate
  • Offering: GitLab.com

Prerequisites:

  • You must have the Owner role or a custom role with the manage_security_policy_link permission to link to the security policy project. For more information, see separation of duties.

The high-level workflow for enforcing policies globally across all subgroups and projects in your GitLab.com namespace:

  1. Visit the Policies tab from your top-level group.

  2. In the subgroup, go to the Policies tab and create a test policy.

    You can create a policy as disabled for testing. Creating the policy automatically creates a new security policy project under your top-level group. This project is used to store your policy.yml or policy-as-code.

  3. Check and set permissions in the newly created project as desired.

    By default, Owners and Maintainers are able to create, edit, and delete policies. Developers can propose policy changes but cannot merge them.

  4. In the security policy project created within your subgroup, create the policies required.

    You can use the policy editor in the Security Policy Management project you created, under the Policies tab. Or you can directly update the policies in the policy.yml file stored in the newly-created security policy project Security Policy Management - security policy project.

  5. Link up groups, subgroups, or projects to the security policy project.

    As a subgroup owner, or project owner with proper permissions, you can visit the Policies page and create a link to the security policy project. Include the full path and the project's name should end with "- security policy project". All linked groups, subgroups, and projects become "enforceable" by any policies created in the security policy project. For details, see Link to a security policy project.

  6. By default, when a policy is enabled, it is enforced on all projects in linked groups, subgroups, and projects.

    For more granular enforcement, add a policy scope. A policy scope allow you to enforce policies against a specific set of projects or against projects containing a set of compliance framework labels.

  7. If you need additional restrictions, for example to block inherited permissions or require additional review or approval of policy changes, you can create an additional policy scoped only to your security policy project and enforce additional approvals.

Enforce policies globally in GitLab Dedicated or GitLab Self-Managed

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

Prerequisites:

  • You must have the Owner role or a custom role with the manage_security_policy_link permission to link to the security policy project. For more information, see separation of duties.
  • To support approval groups globally across your instance, enable security_policy_global_group_approvers_enabled in your GitLab instance application settings.

The high-level workflow for enforcing policies across multiple groups:

  1. Create a separate group to contain your policies and ensure separation of duties.

    By creating a separate standalone group, you can minimize the number of users who inherit permissions.

  2. In the new group, visit the Policies tab.

    This serves as the primary location of the policy editor, allowing you to create and manage policies in the UI.

  3. Create a test policy (you can create a policy as disabled for testing).

    Creating the policy automatically creates a new security policy project under your group. This project is used to store your policy.yml or policy-as-code.

  4. Check and set permissions in the newly created project as desired.

    By default, Owners and Maintainers are able to create, edit, and delete policies. Developers can propose policy changes but cannot merge them.

  5. In the security policy project created in your subgroup, create the policies required.

    You can use the policy editor in the Security Policy Management project you created, under the Policies tab. Or you can directly update the policies in the policy.yml file stored in the newly-created security policy project Security Policy Management - security policy project.

  6. Link up groups, subgroups, or projects to the security policy project.

    As a subgroup owner, or project owner with proper permissions, you can visit the Policies page and create a link to the security policy project. Include the full path and the project's name should end with "- security policy project". All linked groups, subgroups, and projects become "enforceable" by any policies created in the security policy project. For more information, see link to a security policy project.

  7. By default, when a policy is enabled, it is enforced on all projects in linked groups, subgroups, and projects. For more granular enforcement, add a policy scope. A policy scope allows you to enforce policies against a specific set of projects or against projects that contain a set of compliance framework labels.

  8. If you need additional restrictions, for example to block inherited permissions or require additional review or approval of policy changes, you can create an additional policy scoped only to your security policy project and enforce additional approvals.

Link to a security policy project

To enforce the policies contained in a security policy project against a group, subgroup, or project, you link them. By default, all linked entities are enforced. To enforce policies granularly per policy, you can set a policy scope in each policy.

Prerequisites:

  • You must have the Owner role or custom role with themanage_security_policy_link permission to link to the security policy project. For more information, see separation of duties.
  • You must have at least the Reporter role or custom role with the manage_security_policy_link permission to the project you want to assign as the security policy project. For more information, see separation of duties.

To link a group, subgroup, or project to a security policy project:

  1. On the left sidebar, select Search or go to and find your project, subgroup, or group.
  2. Select Secure > Policies.
  3. Select Edit Policy Project, then search for and select the project you would like to link from the dropdown list.
  4. Select Save.

To unlink a security policy project, follow the same steps but instead select the trash can icon in the dialog. You can link to a security policy project from a different subgroup in the same top-level group, or from an entirely different top-level group. However, when you enforce a pipeline execution policy, users must have at least read-only access to the project that contains the CI/CD configuration referenced in the policy to trigger the pipeline.

Viewing the linked security policy project

All users who have access to the project policy page and are not project owners instead view a button linking out to the associated security policy project.

Deleting a security policy project

Version history

  • Deletion protection for security policy projects was introduced in GitLab 17.8 with a flag named reject_security_policy_project_deletion. Enabled by default.
  • Deletion protection for groups that contain security policy projects was introduced in GitLab 17.9 with a flag named reject_security_policy_project_deletion_groups. Enabled by default.
  • Deletion protection for security policy projects and groups that contain security policy projects is generally available in GitLab 17.10. Feature flags reject_security_policy_project_deletion and reject_security_policy_project_deletion_groups removed.

To delete a security policy project or one of its parent groups, you must remove the link to it from all other projects or groups. Otherwise, an error message is displayed when you attempt to delete a linked security policy project or a parent group.