## Background Security and compliance teams need simpler, more intuitive tools to manage security policies at scale. As organizations grow their GitLab adoption, the current repository-based approach to policy management creates unnecessary complexity - requiring customers to manage multiple security policy projects, navigate complex permission structures, and work with YAML files even for simple policy changes. This initiative fundamentally reimagines how security policies are managed within GitLab. Rather than storing policies in security policy projects, policies will be database-native objects with optional policy-as-code support. This shift enables centralized management, granular UI-based permissions, and a single pane of glass for organization-wide policy visibility. {width=1912 height=1050} ### Current Challenges - Complex policy management across multiple security policy projects - Limited visibility into policy enforcement across the organization - Performance bottlenecks with current implementation - Complex UX around managing policies ### Customer Benefits **Simpler Centralized Management**: Customers gain a single point of control for all security policies across their entire GitLab organization, eliminating the need to manage multiple security policy projects scattered across different groups. Paired with improvements to remove "policy as code" as a requirement for creating policies, this will provide a much clearer single pane of glass, while optionally still allowing for advanced DevSecOps configuration through a central `policy.yml`. **Better access control and permission management:** By restructuring policies to manage them atomically and adding new permissions directly within the UI, database, and APIs, we can provide clarity in ownership and impact of each policy stored in the central repository. **Easier Administration**: Security teams can manage up to 5,000 policies from one location instead of navigating complex hierarchies and multiple repositories, reducing administrative overhead by an estimated 60-80%. **Enhanced Visibility**: Organization admins and security personas with appropriate permissions will gain comprehensive oversight of which policies are applied where, solving the current "blind spot" problem where teams can't easily track policy enforcement across their GitLab instance. Any policy changes will be more easily tracked with the git repository log, audit events, and in the policy UI, reducing effort to centralize changes across thousands of groups/projects. **Reduced Risk**: Centralized policy management reduces the risk of misconfigurations and policy gaps that can occur with distributed management approaches. ### Business Value Proposition **Faster Time to Compliance**: Organizations can implement and enforce security policies across their entire GitLab instance in minutes rather than hours or days. **Reduced Support Burden**: Self-service capabilities and clear documentation reduce the need for support tickets and manual intervention. **Cost Efficiency**: Eliminates the operational overhead of managing complex policy hierarchies, freeing security teams to focus on strategic initiatives rather than administrative tasks. These benefits directly address the pain points identified in customer feedback, particularly around policy visibility, management complexity, and scalability challenges that large organizations face as their GitLab adoption grows. ## Problem Security and compliance teams in large organizations face significant challenges when trying to implement and manage security policies at scale. They lack proper visibility into policy enforcement across their GitLab instance, making it difficult to ensure compliance and respond to security risks effectively. The need to manage multiple security policy projects and navigate complex permission structures creates unnecessary overhead and increases the risk of misconfigurations. Our customers report that as their GitLab adoption grows, managing security policies becomes increasingly time-consuming and error-prone. Policy administrators struggle with understanding which policies are applied to which groups and projects, and they lack efficient tools to manage policies across their organization. The current approach of storing all policies in a single file also creates performance issues when organizations need to scale their policy enforcement. Furthermore, the tight coupling between repository permissions and policy management capabilities makes it difficult for organizations to implement proper separation of duties. This forces them to create complex workarounds or compromise on their security and compliance requirements. ## Solution The proposed solution introduces organization-level security policy management, which centralizes policy storage and management while providing granular access controls and improved visibility. By storing each policy as a separate file in a single organization repository, we can improve both performance and manageability while maintaining the benefits of version control and audit capabilities. This new architecture should allow organizations to scale their policy management to support up to 1000 policies per organization, with efficient controls to ensure no more than 20 policies are applied to any single project or group. The solution includes a robust permission model that allows organization admins to delegate policy management responsibilities without exposing the underlying repository structure. By implementing proper caching mechanisms and optimizing the policy application workflow, we can ensure consistent performance even at scale. The solution also includes comprehensive audit logging and policy propagation tracking, giving security teams the visibility they need to maintain their security and compliance posture effectively. ### Performance Benefits Beyond the UX improvements and improved capabilities that are most immediately impactful to customers, there are also many performance benefits as a result of this improved and streamlined architecture. **Enterprise-Scale Support**: The new architecture much better supports organizations with thousands of policies while maintaining performance, addressing current bottlenecks that impact large enterprises. **Improved Response Times**: Redis-based caching and optimized policy application workflows ensure consistent performance even at scale, reducing policy enforcement latency. **Future-Proof Architecture**: Built to handle 10x current scale, ensuring the solution grows with customer needs. ## Technical Architecture ```mermaid flowchart TD OA["👤 Organization Admin\nManages policies and permissions"] PMN["Organization Admin manages:\n- Policy management permissions\n- Policy scope access\n- User role assignments"] subgraph OR["Organization Repository"] direction LR P1["Scan Execution Policy A\nScope: Group A"] P2["License Approval Policy B\nScope: All Projects"] P3["Pipeline Execution Policy C\nScope: Group B"] P4["MR Approval Policy D\nScope: Project X"] end subgraph Groups["Groups & Projects"] subgraph GA["Group A"] GPA["👤 Policy Admin A\nCan manage Group A policies"] ProjA1["Project A1"] ProjA2["Project A2"] end subgraph GB["Group B"] GPB["👤 Policy Admin B\nCan manage Group B policies"] ProjB1["Project B1"] ProjB2["Project B2"] end subgraph PX["Project X"] PPX["👤 Project Admin X\nCan manage Project X policies"] end end OA --> OR OA --- PMN P1 --> GA P2 --> GA P2 --> GB P2 --> PX P3 --> GB P4 --> PX classDef admin fill:#A989F5,stroke:#7759C2,color:white classDef policy fill:#F0EBF9,stroke:#A989F5 classDef group fill:#F9F9F9,stroke:#666 classDef project fill:white,stroke:#666 classDef note fill:#FDF1DD,stroke:#FCA326,color:black class OA,GPA,GPB,PPX admin class P1,P2,P3,P4 policy class GA,GB group class ProjA1,ProjA2,ProjB1,ProjB2,PX project class PMN note ``` ### Key Components 1. **Organization Repository** - Single security policy project per organization - Each policy stored as a separate file - Git-based version control for policy history - CODEOWNERS support for optional policy approvals - Change tracking and audit logging 2. **Caching & Performance** - Redis-based caching mechanism - Database read models for policy enforcement - Policy propagation tracking system 3. **Access Control** - Organization-level permission management - Policy approval workflows through merge requests (ability to disable it to allow users with permissions to push changes to policies directly) - Dedicated permission system for policy management - Scope-based access control - Role resolution and validation 4. **Integration Layer**: - UI interfaces with policies through API - Policy validation and permission checking - Scope resolution and conflict detection - Change propagation and status tracking ### Limits & Constraints - Maximum 100 policies per organization initially (scalable to 5000) - Maximum 20 policies applied to a single project/group - No policy sharing across organizations - No policy inheritance (flat structure) ## Migration Strategy 1. One-way migration from existing security policy projects 2. 12-month deprecation period for old model 3. All new organization policies will use the new model 4. Gradual rollout plan (details TBD) ## Security & Audit - Comprehensive audit logging for policy changes - Permission validation for policy scope changes - Optional policy approval workflows - Visual indicators for policy propagation status ## Technical Requirements 1. Modify existing policy limits implementation 2. Implement new storage model in organization repository 3. Enhance caching mechanism for improved performance 4. Create new permission management system 5. Develop policy propagation tracking system 6. Implement audit logging 7. Create migration tooling ## Out of Scope - Policy templates - Policy inheritance mechanisms - Cross-organization policy sharing - Changes to existing policy JSON schema ## Metrics for Success - Increased adoption of Security Policies among Ultimate customers - Reduced policy management complexity (measured through user feedback) - Improved policy application performance - Successful migration of existing customers to new model ## Dependencies - Organization feature availability - Changes to policy limits implementation ## Personas ### Primary Personas 1. [Cameron (Compliance Manager)](https://about.gitlab.com/handbook/product/personas/#cameron-compliance-manager) - Primary user who needs to ensure organization-wide policy enforcement - Requires visibility into policy implementation and audit capabilities - Needs to delegate policy management responsibilities while maintaining control 2. [Alex (Security Operations Engineer)](https://about.gitlab.com/handbook/product/personas/#alex-security-operations-engineer) - Responsible for implementing and maintaining security policies - Needs efficient tools to manage policies across multiple groups - Requires visibility into policy effectiveness and compliance ### Secondary Personas 3. [Delaney (Development Team Lead)](https://about.gitlab.com/handbook/product/personas/#delaney-development-team-lead) - Needs to understand which policies apply to their team's projects - Requires clear visibility into policy requirements and violations - Wants to ensure policies don't unnecessarily impact development velocity 4. [Devon (DevOps Engineer)](https://about.gitlab.com/handbook/product/personas/#devon-devops-engineer) - Implements and maintains CI/CD pipelines that must comply with policies - Needs to understand policy impact on automation and deployment processes - Requires clear feedback when policies affect pipeline execution ## Acceptance Criteria ### Organization Admin Experience - [ ] Can view all security policies defined in the organization - [ ] Can manage permissions for policy management across groups - [ ] Can enable/disable policy approval workflow requirement - [ ] Can view policy propagation status and history - [ ] Can access audit logs for policy changes - [ ] Can see which policies are applied to which groups/projects - [ ] Receives notifications about policy application failures ### Policy Admin Experience - [ ] Can create/update/delete policies only for authorized groups - [ ] Can view policies applicable to their authorized scope - [ ] Cannot modify policies outside their scope - [ ] Can see policy propagation status - [ ] Gets clear error messages when attempting unauthorized actions - [ ] Can view policy change history for their scope ### Policy Storage & Management - [ ] Each policy is stored as a separate file in organization repository - [ ] Policy changes are version controlled through Git - [ ] CODEOWNERS rules are respected for policy approvals - [ ] Policy JSON schema validation is maintained - [ ] Policies are properly cached in Redis - [ ] Policy read models are correctly maintained in database ### Performance & Scalability - [ ] System supports up to 100 policies per organization (initially) - [ ] Maximum 20 policies can be applied to a single project/group - [ ] Policy application latency is tracked and visible - [ ] Policy propagation status is accurately reported - [ ] Caching mechanism effectively reduces load on Gitaly ### Migration - [ ] Existing policies can be migrated to new system - [ ] Migration process is non-disruptive - [ ] Failed migrations can be retried - [ ] Migration progress is trackable - [ ] Clear documentation for migration process exists ## Implementation Phases ### Phase 1: Foundation 1. **Infrastructure Setup** - Create organization-level policy storage structure - Implement new policy limits logic - Set up basic permission management system - Create initial database schema changes 2. **Core Policy Management** - Implement single file per policy storage - Basic policy CRUD operations - Policy validation system - Initial caching mechanism ### Phase 2: Access Control & UI 1. **Permission System** - Implement granular permission management - Policy scope validation - Integration with organization permissions - Audit logging system 2. **User Interface** - Organization admin policy overview - Policy management UI updates - Permission management interface - Policy status visualization ### Phase 3: Performance & Caching 1. **Enhanced Caching** - Implement Redis caching improvements - Optimize policy application flow - Add policy propagation tracking - Performance monitoring and metrics 2. **Scalability Improvements** - Batch policy processing - Background job optimizations - Cache invalidation strategy - Load testing and benchmarking ### Phase 4: Migration & Deprecation 1. **Migration Tools** - Develop migration scripts - Migration status tracking - Rollback capabilities - Migration documentation 2. **Deprecation Process** - Deprecation warnings - Migration guides - Customer communication plan - Support documentation ### Phase 5: Polish & Stabilization - UI/UX improvements based on feedback - Performance optimizations - Documentation updates - Bug fixes and stability improvements ## Risk Mitigation Strategies ### Technical Risks 1. **Performance Degradation** - Risk: Large number of policies could impact system performance - Mitigation: * Implement aggressive caching strategy * Use background processing for non-critical updates * Add performance monitoring and alerting * Establish performance benchmarks early * Implement circuit breakers for policy application 2. **Migration Failures** - Risk: Data loss or inconsistency during migration - Mitigation: * Create comprehensive backup strategy * Implement dry-run migration option * Build rollback capability * Add detailed migration state tracking * Create recovery procedures for partial migrations 3. **Cache Invalidation Issues** - Risk: Stale or inconsistent policy data - Mitigation: * Implement version tracking for cached policies * Add cache warming mechanisms * Create cache health monitoring * Build automatic recovery procedures * Implement grace period for policy updates 4. **Gitaly Performance** - Risk: Increased load on Gitaly due to policy file operations - Mitigation: * Implement request batching * Add rate limiting for policy operations * Optimize git operations * Monitor Gitaly metrics closely ### Business Risks 1. **User Adoption** - Risk: Users resist moving to new system - Mitigation: * Create comprehensive migration guides * Provide early access program * Offer migration support * Collect and act on user feedback * Plan gradual rollout strategy 2. **Customer Impact** - Risk: Service disruption during migration - Mitigation: * Create detailed rollout plan * Implement feature flags for gradual rollout * Establish clear communication channels * Prepare rollback procedures * Schedule migrations during low-traffic periods 3. **Complex Permissions** - Risk: Users confused by new permission model - Mitigation: * Create clear documentation * Implement permission validation * Add permission visualization tools * Provide training materials * Offer support during transition ### Operational Risks 1. **Scale and Growth** - Risk: System cannot handle future growth - Mitigation: * Design for 10x current scale * Implement horizontal scaling capability * Add monitoring and alerting * Create capacity planning guidelines * Regular performance testing 2. **Support Burden** - Risk: Increased support tickets during transition - Mitigation: * Prepare support documentation * Train support team early * Create troubleshooting guides * Implement self-service tools * Monitor common issues and create FAQs 3. **Audit Compliance** - Risk: Missing audit trail during migration - Mitigation: * Implement comprehensive audit logging * Maintain policy history * Create audit reporting tools * Ensure compliance with retention policies * Add audit verification tools ## Contingency Plans 1. **Performance Issues** - Ability to temporarily disable policy propagation - Fallback to cached policies - Emergency scale-up procedures 2. **Migration Problems** - Automatic rollback procedures - Point-in-time recovery capability - Manual intervention playbooks 3. **Critical Bugs** - Feature flag kill switch - Revert procedures - Incident response plan ## Post-Implementation Monitoring 1. **System Health** - Policy application latency - Cache hit rates - Gitaly operation metrics - Background job performance 2. **User Impact** - Policy creation/update success rates - UI interaction metrics - Support ticket trends - User feedback tracking 3. **Business Metrics** - Adoption rates - Migration success rates - Policy usage patterns - Performance against SLOs ## Related Epics/Issues * https://gitlab.com/gitlab-org/gitlab/-/issues/444547+ * https://gitlab.com/gitlab-org/gitlab/-/issues/519764+ * https://gitlab.com/groups/gitlab-org/-/epics/13488+ * https://gitlab.com/groups/gitlab-org/-/epics/11156+ * https://gitlab.com/gitlab-org/gitlab/-/issues/427759+ * https://gitlab.com/groups/gitlab-org/-/epics/5446+ * https://gitlab.com/gitlab-org/gitlab/-/issues/515816+