Prepare Policies V2 Architectural Blueprint

Why is this change being made?

This merge request introduces the architectural blueprint for Security Policies v2, which transforms policy management from a distributed, repository-centric model to a centralized, database-driven architecture.

The current repository-based Security Policy Projects (SPPs) approach creates significant challenges for organizations managing policies at scale:

• Repository fragmentation makes it difficult to maintain consistency and visibility
• Every policy change requires MR creation and approval, creating friction for security teams
• All policies stored in one YAML file per repository creates merge conflicts and parsing complexity
• Policy management rights tied to repository access complicates permission management
• No central view of organization-wide policy enforcement and compliance status
• Complex logic required to detect policy changes in files and trigger database updates

This architectural blueprint proposes a database-first approach that maintains the same powerful policy enforcement capabilities while dramatically simplifying the management experience, enabling organizations to scale from hundreds to thousands of policies with 15-minute propagation SLAs and support for groups containing 200k+ projects.

Author and Reviewer Checklist

Please verify the check list and ensure to tick them off before the MR is merged.

• Provided a concise title for this [Merge Request (MR)][mr]
• Added a description to this MR explaining the reasons for the proposed change, per [say why, not just what][say-why-not-just-what]
• Assign reviewers for this MR to the correct
  • The [when to get approval][when-to-get-approval] handbook section explains when [DRI][dri] approval is required
  • The [who can approve][who-can-approve] handbook section explains how to identify the DRI
  • If the MR does not require DRI approval, consider asking someone on your team, such as your manager.
  • The approver may merge the MR. If they approve but don't merge, you can merge.
• For transparency, share this MR with the audience that will be impacted.
  • Team: For changes that affect your direct team, share in your group Slack channel
  • Department: If the update affects your department, share the MR in your department Slack channel
  • Division: If the update affects your division, share the MR in your division Slack channel
  • Company: If the update affects all (or the majority of) GitLab team members, post an update in [#whats-happening-at-gitlab][whats-happening-at-gitlab-slack] linking to this MR

Architecture Overview

This blueprint proposes transforming Security Policies from a repository-centric model to a database-first architecture that separates policy configuration from policy application while maintaining enforcement consistency.

Key Architectural Changes

1. Policy Templates: Reusable policy configurations created at organization or top-level group levels, stored as individual database entities rather than bundled in single files.

2. Policy Applications: Separate scope-specific assignments that define where templates are applied, enabling the same template to be used across multiple groups or projects.

3. Centralized Database Storage: Single source of truth for all policy data, with optional repository sync for customers wanting policy-as-code workflows.

4. Atomic Management: Each policy managed as separate entity with individual change tracking, eliminating complex file parsing logic.

5. Background Processing: Asynchronous application of policies to large scopes with progress tracking and 15-minute SLA.

User Experience Transformation

• Organization Admins gain central dashboard with complete visibility and can nominate Policy Admins
• Policy Admins create reusable templates and apply them across authorized scopes
• Group Owners can create group-scoped templates and apply available templates to their projects
• All Users benefit from direct UI editing replacing merge request workflows

Benefits Over Current Approach

Aspect	Policies v1	Policies v2
Data Storage	Multiple repositories, single YAML files	Centralized database, atomic policies
User Interface	MR creation and approval	Direct UI editing
Permissions	Repository-based access	Dedicated RBAC roles
Change Detection	Complex file parsing logic	Simple database change tracking
Scalability	Limited by repository sync	Background processing with SLA
Visibility	Fragmented across repositories	Organization-wide dashboard

This architectural blueprint provides a foundation for future implementation work that will dramatically improve the policy management experience for GitLab customers.