## Summary Artifact Registry requires product-specific roles with a closed-by-default authorization model. The Authorization team will define roles and permissions, while Organizations owns the role assignment UI. This PRD outlines the agreed-upon MVC solution and implementation requirements. ## Problem Statement Artifact Registry is the first modular service on Organizations requiring explicit role assignment. The authorization model must: - Support closed-by-default access (industry standard for enterprise tools) - Enable efficient bulk role assignment for users - Provide baseline permissions with fine-grained control options - Align with the north star for modular services on Organizations ## Agreed MVC Solution Per alignment meetings between AR, Organizations, and Authorization teams ([May 20-22, 2026](https://gitlab.com/gitlab-org/gitlab/-/work_items/593455#note_3374942986)): ### Role Model: Product-Specific Roles Artifact Registry will use **product-specific roles** scoped to AR: | Role | Permissions | |------|-------------| | **Artifact Admin** | Full AR management including namespace-level configuration | | **Artifact Manager** | Repository management, lifecycle policies, access rules | | **Artifact Contributor** | Publish and read artifacts | | **Artifact Viewer** | Read-only access to artifacts and repositories | **Rationale**: Constrained scope reduces impact to other products and Organization-level default roles. Less reliance on custom roles roadmap. <details> <summary> ### Default permission buckets </summary> See [Artifact Registry Authorization ADR](https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/artifact_registry/decisions/021_authorization/#default-permission-buckets). Each role maps to a default set of permissions. These defaults are the starting point before user-defined access rules are applied. In the matrix below, columns are the four Artifact roles and rows are permissions; ✓ means the role holds that permission by default, and a blank cell means it does not. | Permission | Viewer | Contributor | Manager | Admin | |------------|:------:|:-----------:|:-------:|:-----:| | `read_artifact` | ✓ | ✓ | ✓ | ✓ | | `create_artifact` | | ✓ | ✓ | ✓ | | `update_artifact` | | | ✓ | ✓ | | `delete_artifact` | | | ✓ | ✓ | | `read_repository` | ✓ | ✓ | ✓ | ✓ | | `create_repository` | | | | ✓ | | `update_repository` | | | ✓ | ✓ | | `delete_repository` | | | | ✓ | | `read_repository_lifecycle_policy` | | | ✓ | ✓ | | `create_repository_lifecycle_policy` | | | ✓ | ✓ | | `update_repository_lifecycle_policy` | | | ✓ | ✓ | | `delete_repository_lifecycle_policy` | | | ✓ | ✓ | | `read_namespace_lifecycle_policy` | | | | ✓ | | `create_namespace_lifecycle_policy` | | | | ✓ | | `update_namespace_lifecycle_policy` | | | | ✓ | | `delete_namespace_lifecycle_policy` | | | | ✓ | | `read_repository_access_rule` | | | ✓ | ✓ | | `create_repository_access_rule` | | | ✓ | ✓ | | `update_repository_access_rule` | | | ✓ | ✓ | | `delete_repository_access_rule` | | | ✓ | ✓ | | `read_namespace_access_rule` | | | | ✓ | | `create_namespace_access_rule` | | | | ✓ | | `update_namespace_access_rule` | | | | ✓ | | `delete_namespace_access_rule` | | | | ✓ | | `create_upstream_association` | | | ✓ | ✓ | | `update_upstream_association` | | | ✓ | ✓ | | `delete_upstream_association` | | | ✓ | ✓ | | `create_artifact_quarantine` | | | ✓ | ✓ | | `delete_artifact_quarantine` | | | ✓ | ✓ | </details> ### Authorization Model: Closed-by-Default - Organization membership does NOT automatically grant AR access - Users must be explicitly assigned an AR role to access the product - Org Owners are automatically bootstrapped as Artifact Admins - All other users require manual/bulk assignment ### Permission Layers 1. **Default role permissions**: Baseline permissions per role 2. **Repository overrides**: Assign different roles per repository 3. **Access rules**: Fine-grained policies that can only tighten (never expand) default permissions ## Ownership & Responsibilities ### Authorization Team (@NellyVahab @ipelaez1 @imand3r @jpr0c) - **Role creation**: Define AR-specific roles in YAML (`config/authz/roles`) - **Permission mapping**: Define role → permission buckets - **Security principles**: Apply authorization framework and policy evaluation - **Role assignment**: Assigning AR roles to users (API level) ### Organizations Team (@jblack7 @jason_istakinganap) - **Role assignment UI**: Build user management interface for assigning AR roles - **Bulk assignment**: Enable efficient assignment for thousands of users - **Organization admin area**: Provide container for product-specific role management ### Artifact Registry Team (@trizzi @alyssatrinh @10io) - **AR-specific UI**: Repository overrides, access rules, AR settings - **Permission requirements**: Define what each role can do in AR - **Collaboration**: Support Organizations team with AR-specific context ## Delivery Timeline ### 19.2 Closed Beta (June 2026) - **Workaround**: API-only role assignment via Relationships API - **Bootstrapping**: Org Owners automatically assigned Artifact Admin role - **Scope**: Small group of design partners, limited user testing ### 19.4 Open Beta (Q3 2026) - **Required**: Organizations user management UI for role assignment - **Bulk assignment**: UI support for assigning roles to multiple users - **Monetization blocker**: Cannot monetize without user management UI ### GA (Future) - Full role management experience - Custom roles integration (when available) - Teams integration (when available) ## Technical Requirements ### Role Definition (Authorization) - [ ] Define AR roles in `config/authz/roles` YAML - [ ] Review and decompose `manage_*` permissions per GitLab conventions * [ ] Break down `manage_repository_lifecycle_policy`, `manage_namespace_lifecycle_policy`, `manage_repository_access_rule`, `manage_namespace_access_rule`, `manage_upstream`, `manage_cache` into granular CRUD operations - [ ] Map roles to permissions (management vs. artifact operations) - [ ] Implement repository-level role overrides (most specific assignment wins) * [ ] Allow assigning different roles per repository that override organization-level assignments (is this deferred?) - [ ] Share role definitions with AR team for GATE simulation layer - [ ] Implement access rules that can tighten (never expand) default permissions (is this deferred?) ### Bootstrapping (Authorization + AR) - [ ] Hook into AR activation flow to assign Org Owners as Artifact Admins - [ ] Sync Org Owner changes (additions/removals) to maintain role assignments - [ ] Implementation issue: [#601893](https://gitlab.com/gitlab-org/gitlab/-/work_items/601665) ### Relationships API (Authorization) - [ ] Expose GraphQL wrapper in Rails for Relationships API (gRPC) - [ ] Support JWT authentication for API calls - [ ] Enable bulk role assignment operations ### User Management UI (Organizations) - [ ] Organization-level user management page - [ ] Bulk user selection and role assignment - [ ] Product-specific role assignment (AR roles) - [ ] Delivery target: 19.4 (Q3 2026) ## Permission Model Details ### Management Permissions (Fixed Mappings) - `read_repository`, `create_repository`, `update_repository`, `delete_repository` - `manage_repository_lifecycle_policy`, `manage_namespace_lifecycle_policy` - `manage_repository_access_rule`, `manage_namespace_access_rule` - `manage_upstream`, `manage_cache` ### Artifact Permissions (Can Be Tightened by Access Rules) - `read_artifact`, `create_artifact`, `update_artifact`, `delete_artifact` ## Open Questions 1. **Permission naming**: Need to review permission names per [GitLab conventions](https://docs.gitlab.com/ee/development/permissions/conventions.html) - avoid `admin`, `manage`, `view` (@NellyVahab to provide recommendations) 2. **Organizations capacity**: Can Organizations deliver user management UI by 19.4? (@jblack7 @mandrewsgl) ## North Star (by @NellyVahab) > The north star remains as a single platform authorization model where modules contribute role definitions, permissions, resources, and policy hooks, while the platform provides the ability to create roles, evaluation, governance, and explainability. > > 1. Organization becomes the primary control plane for access management > 2. Teams become the main scaling mechanism > 3. Modules define authorization model, permissions, policies, and user access > 4. Custom roles become the main customer flexibility layer > 5. Governance and explainability are first-class ## Success Criteria - [ ] Org Owners can assign AR roles via API in 19.2 (TBC) - [ ] Org Owners can assign AR roles via UI in 19.4 (TBC) - [ ] Bulk assignment supports thousands of users efficiently - [ ] Closed-by-default model is secure and clear to users - [ ] Role model accommodates future custom roles and Teams ## References - [MVC Alignment Slides](https://docs.google.com/presentation/d/1AYOr57VSeSC0N1rY7XnqMiwf8o8bi-8zEbvhBHQgSuA/edit) - [ADR-021: Authorization](https://gitlab.com/gitlab-com/content-sites/handbook/-/blob/ee7664add095d2587199e18ea8a203d294df2814/content/handbook/engineering/architecture/design-documents/artifact_registry/decisions/021_authorization.md) - [#593455](https://gitlab.com/gitlab-org/gitlab/-/work_items/593455) - Full discussion thread - [#590721](https://gitlab.com/gitlab-org/gitlab/-/work_items/590721) - Custom roles roadmap