## Problem Statement The Policy Store experiment ([&22027](https://gitlab.com/groups/gitlab-org/-/work_items/22027)) introduces centralized CD deployment policies managed at the group level. The core DB schema ([#604367](https://gitlab.com/gitlab-org/gitlab/-/work_items/604367)) defines how policy records are stored, but it does not address **who can do what** with those policies. The [Policy Store gem](https://gitlab.com/gitlab-org/security-risk-management/security-policies/projects/policy-store) defines a dedicated permissions model via a `security_policy_members` table with custom Owner/Manager roles, rather than reusing GitLab's existing RBAC. This issue designs how that model integrates with the monolith for the 19.4 experiment, resolves the open scope-permissions boundary problem, and starts implementation in 19.3. Without a permissions model, the 19.4 experiment cannot answer: - Who can create, edit, enable/disable, and delete CD deployment policies in a group? - Who can transition a policy between enforcement modes (audit → warn → enforce)? - How do we prevent users from scoping policies to projects beyond their permission boundaries? - How do the experiment toggles (instance + group) interact with policy management permissions? - What permissions does the CD deploy driver need to consult the Policy Store at a deployment gate? ## Goals 1. **Design** the permissions data model for the Policy Store, integrating the gem's Owner/Manager role model with GitLab's existing RBAC in the monolith 2. **Resolve** the scope-permissions boundary problem identified in the gem README as a critical unsolved problem 3. **Document** the design decisions as a reference for the Policy Engine team and CD team (customer zero) 4. **Start implementation** of the agreed model within 19.3 ## Background: Gem Permissions Model The Policy Store gem README defines the following starting point: | Role | Capabilities | |------|-------------| | **Owner** | Manage members, delete policy, read/update policy | | **Manager** | Read policy, update policy | Design constraints from the gem: - **Single-user permissions first**, not group-based - **Platform administrators** (self-managed) have de facto owner permissions - **Orphan prevention**: block removal of the last owner - **Scope is evaluated via Rego and cached** — no denormalized scope tables - **Vision**: a special "policy manager" role where security users can manage policies for groups without needing direct code access to those groups The `security_policy_members` table (user + role: owner/manager) is the expected schema addition. ## Scope ### Design questions to resolve 1. **RBAC integration:** The gem defines custom Owner/Manager roles. How do these map to GitLab's existing group/project roles (Owner, Maintainer, Developer) in the monolith? Are they additive (a new permission layer on top of RBAC), or do existing group Owners automatically get policy Owner permissions? 2. **Scope-permissions boundary (critical unsolved problem):** When a user scopes a policy to target specific projects, how do we validate that the scope doesn't exceed their permission boundaries? A security team member may need to set policies across projects they don't have code access to — this is the "policy manager" vision. What validation happens at policy creation/edit time vs. at evaluation time via Rego? 3. **Mode transition permissions:** Is transitioning a policy from `audit` to `enforce` a higher-privilege operation than editing other policy fields? Enforce mode can block production deployments — this is a materially different risk level than editing a policy name. Should this require Owner role, or is Manager sufficient? 4. **Toggle interaction:** The experiment toggles (instance-level admin setting, group-level owner toggle) gate the entire feature. What role is required to enable the group-level toggle? Is this the same as the policy Owner role, or is it tied to the existing group Owner role? 5. **Engine access:** How does the Policy Engine (or the CD deploy driver) authenticate and authorize when looking up policies at a deployment gate? In the 19.4 monolith experiment this is an internal call, but the permissions model should not assume that — the gem's target architecture separates these into distinct deployment units. 6. **Organizations readiness:** How does the Organizations data model affect permission resolution? (Depends on the org-readiness spike outcome from [#604367](https://gitlab.com/gitlab-org/gitlab/-/work_items/604367).) ### Design deliverables - Permission matrix: operations × roles (Owner/Manager/platform admin) × scope (group / project) - `security_policy_members` table schema (user + role + policy/group association) - Scope-permissions boundary resolution: what's validated at write time vs. evaluation time - DeclarativePolicy (or equivalent) authorization class integrating the custom role model - Documentation of decisions for cross-team consumers (Policy Engine team, CD team) ### Implementation (start in 19.3) - `security_policy_members` migration with appropriate constraints - Orphan prevention: validation blocking removal of the last Owner - Authorization policy class (`PolicyStorePolicy` or equivalent) with specs - Integration with the core schema models from [#604367](https://gitlab.com/gitlab-org/gitlab/-/work_items/604367) - Guard clauses on any service-layer entry points that exist by end of milestone ## Acceptance Criteria - [ ] Permission matrix documented: Owner/Manager roles mapped to all policy operations (CRUD, mode transitions, member management) - [ ] RBAC integration decided: how custom roles relate to existing GitLab group/project roles - [ ] Scope-permissions boundary resolved and documented (write-time validation vs. Rego evaluation) - [ ] Mode transition permissions decided (Manager-sufficient or Owner-required?) - [ ] `security_policy_members` migration merged with orphan prevention constraint - [ ] DeclarativePolicy (or equivalent) authorization class created with specs - [ ] Design documented for the Policy Engine team and CD team - [ ] Organizations impact on permission resolution addressed (may depend on org-readiness spike) - [ ] Design does not preclude the future "policy manager" role vision (security users managing policies without code access) ## Dependencies - [#604367](https://gitlab.com/gitlab-org/gitlab/-/work_items/604367) — Policy Store: policy DB schema and storage (monolith) — the core schema this permissions model builds on - [#604407](https://gitlab.com/gitlab-org/gitlab/-/work_items/604407) — Policy Store: define interface between Policy Store and Policy Engine — engine access permissions must align with the interface contract - [#604287](https://gitlab.com/gitlab-org/gitlab/-/work_items/604287) — Experimental toggle system — toggle enablement permissions interact with policy management permissions - Organizations readiness spike (issue TBD) — may affect how permission resolution works at the namespace level - [Policy Store gem](https://gitlab.com/gitlab-org/security-risk-management/security-policies/projects/policy-store) — source of truth for the target permissions model ## Complexity **M** (1-2 weeks, cross-functional design + backend implementation start) ## Update: Simplified permissions model for the experimental release (19.4) Following a discussion with the team, we're simplifying the approach for the experimental release rather than implementing the full per-policy Owner/Manager role model originally described in this issue. ### What changes Instead of introducing a dedicated `security_policy_members` table and custom Owner/Manager roles, we'll use GitLab's existing group membership and [DeclarativePolicy](https://gitlab.com/gitlab-org/ruby/gems/declarative-policy) framework: - **Top-level group Owners** have full access to manage policies (create, read, update, delete) - **All other roles** have no access to the Policy Store - Group Owners can optionally delegate policy management to members via **custom roles** with the granular `update_security_policy` permission ### What stays the same The per-policy Owner/Manager role system (as originally designed in this issue and the Policy Store gem) remains the right target architecture for when the Policy Store is extracted into its own service. This simplification does not preclude that future path. ### POC See !248469 for a proof of concept implementing this approach.