## Problem Org-scope resources like Artifact Registry, and future ones like CD and Teams, each need a way for Org admins to grant product-specific access to users and groups. Without a UI, Org admins cannot manage AR access in-product, adoption is capped, and every access change goes through API scripting or Support. Building a separate settings page for each product would fragment the surface and force customers to learn a new pattern per product. ## Outcome A single Resource Access page at the Org level where Org admins manage role assignments for any Org-level product (AR at launch, CD and others as they come online). One primitive, one interaction model, one audit trail. Product teams plug in a role catalog; the surface handles list, invite, edit, revoke, and precedence uniformly. ## Why now - AR moves out of closed beta in 19.4. UI parity with the API is the gating item for external access. - Building a Resource Access primitive now avoids a proliferation of per-product settings pages later. It is the leverage point for future product plug-ins (CD, Teams) without added coordination cost. - UI-driven grants generate audit events that scripted API calls often skip. Compliance and audit expectations for enterprise Orgs make this a GA blocker, not a nice-to-have. ## Users Primary: Org owners, Org admins, and AR admins on GitLab.com Organizations. ## Design proposal Authoritative direction: [#603700](https://gitlab.com/gitlab-org/gitlab/-/work_items/603700), note by @jason_istakinganap (aligned with the Organizations team in person, 2026-07-27). Supporting design prototype (page structure holds; role assignment and the modal flow are being reworked from this baseline): https://gitlab-org.gitlab.io/ci-cd/package-stage/artifact-registry-design-proposal/users/index.html Figma: https://www.figma.com/design/b5gaaEDjfxZbphoRQ3jVGv/AR-concepting?node-id=3324-45326 ## Scope ### Surface and navigation - New page: Resource Access, under the Org. Location surfaces role assignment for every Org-level product in one place, similar to the group membership page but shared across resources. - Access to the page is gated by the Org Admin role. Regular Org members do not see it. - List view scoping: - Org admin: sees all users who have any resource role in the Org. - Resource admin (e.g. AR admin): sees only users who have a role for their resource. ### List view - Users and groups listed with their resource role assignments and source (direct assignment vs group membership). - Sortable and filterable. Filter and summary cards at the top of the surface follow the same pattern as the reference prototype (Pending approval, Administrators, Without 2FA) subject to design confirmation for Resource Access framing. ### Add via modal - Primary action opens a modal that: - Asks the admin to pick a resource (e.g., Artifact Registry, CD). - Presents the role options for that resource. Options change with resource selection. - Adds one or more users or groups with the selected role. - Group invitation is supported (add an entire group with a resource role). - Confirmation is inherent in the modal flow. Cancel closes the modal without state change. ### Edit and revoke - Row-level edit and revoke actions per principal. Confirmation required for both. - Revoke updates the list without a page reload. ### Role catalog for AR (launch resource) Role names and one-line descriptions must match the strings the AR team ships with the backend role definitions. - Artifact Admin. Full administrative control of Artifact Registry within the Org. - Artifact Manager. Manage repositories, settings, and access within AR. - Artifact Contributor. Push and manage artifacts. Read all AR resources. - Artifact Viewer. Read-only access to AR resources. ### Audit and Display When a user has a role from multiple sources (direct + one or more group memberships), the row shows the effective role and its source, using design-approved copy such as "Your roles from multiple sources determine your effective permissions". Contributing sources are visible on demand. ### Guardrails - The UI blocks removal of the last Org owner and surfaces a clear explanation. - The UI shows a warning before an admin changes their own role. - Empty state with the copy "No one has AR access yet, add your first member" and a primary action to open the add modal. ### Repo-level raise-only override Called out in partner-team scope (#606444, story 7). Not yet covered in the Resource Access design. GA scope of this epic includes: - An Org owner or AR admin can grant a higher role than the Org default on a specific repository. - The UI prevents lowering below the Org default. If Resource Access defers this to a follow-on, the deferral is documented on this epic before GA. ## Out of scope - Backend AuthZ implementation of role association. Delivered separately by the AuthZ team. - Adding CD, Teams, or other product role catalogs at this epic's GA. The surface accepts them, but only AR ships plugged in. - Cross-product bulk actions in one operation (assign a user a role in AR and CD in the same click). - Bulk import of role assignments from CSV or SAML mapping. Open questions (Jason's note, not yet resolved) - Default state of the member list. Empty on first load, or pre-filled with Org members? Both options are being prototyped. - Multi-role in one modal. How to represent adding a user to multiple resources or multiple roles inside a single modal invocation. - Bulk "assign to all users". Whether the surface supports an affordance to assign a role to every user in the Org at once. - Per-resource vs single-list scoping. Raised by @NellyVahab. Should the Resource Access page show one unified user list, or per-resource lists? Either way the UX pattern is the same. Decision needed to lock schema. - Design copy. Empty states, precedence explainer, and modal microcopy are TBD. ## Acceptance criteria Feature is complete when all of the following are true, verified in a shipping release: - [ ] Navigation. The Resource Access page is reachable from the Org and is gated by the Org Admin role. Regular members cannot access it. - [ ] List view. Users and groups with an AR role are listed. Columns and filters follow the design. Sort works on at least Name and Last activity. - [ ] Scoped visibility. Org admins see all users; resource admins (e.g., AR admin) see only users with a role for their resource. Verified with fixture users of each role. - [ ] Add modal. A single modal handles adding one or more principals. Resource picker changes the role options. Groups can be added. - [ ] Confirmation. The modal's Add action is the confirmation step. Cancel closes without state change. No orphan writes. - [ ] Role catalog. The four AR roles render with the exact names and one-line descriptions supplied by the AR team. - [ ] Edit flow. Row-level edit changes a principal's role. Confirmation required. - [ ] Revoke flow. Row-level revoke removes a principal's role. Confirmation required. List updates without a page reload. - [ ] Source visibility. Each row shows the source of the effective role (direct or specific group). All contributing sources are visible on demand. - [ ] Precedence copy. The precedence explainer uses design-approved copy such as "Your roles from multiple sources determine your effective permissions". - [ ] Empty state. When no principals have AR access, the empty state renders "No one has AR access yet, add your first member" plus a primary action that opens the add modal. - [ ] Last-owner guardrail. The UI blocks removal of the last Org owner and shows an explanation. - [ ] Self-role-change warning. The UI shows a warning before an admin changes their own role and requires explicit confirmation. - [ ] Repo-level override. A raise-only override at the repository level can be applied and cannot lower the effective role below the Org default. If deferred, the deferral is documented on this epic before GA. - [ ] Audit. Every add, edit, and revoke writes an audit event with actor, target principal(s), resource, role, and timestamp. Audit schema matches the API path from closed beta. - [ ] Accessibility. The Resource Access page meets WCAG 2.1 AA. Keyboard navigation covers all interactive elements. Screen-reader labels are present on the modal, role selectors, and confirmation dialogs. - [ ] Documentation. User docs describe the Resource Access page, four-role catalog, precedence rules, and scoped visibility. Internal enablement notes are handed to CS and Support. - [ ] Feature flag. The surface ships behind a feature flag that defaults on for the AR GA cohort and can be gated per Organization if needed. ## Proposed Success metrics Measured over the first 60 days after GA of AR role management via Resource Access: - UI-vs-API share. At least 70 percent of AR role changes are performed via the Resource Access UI rather than the API. - Adoption breadth. At least 60 percent of active AR-using Organizations have configured at least one AR role assignment via the UI. - Modal completion rate. At least 85 percent of add-modal opens result in a completed role assignment (indicating the flow itself does not lose users). - Support deflection. Support tickets categorized under AR access setup or AR role assignment trend down at least 40 percent versus the closed-beta baseline in the equivalent window. - Assignment error rate. Fewer than 2 percent of role assignment attempts result in a user-visible error. ## Dependencies - AuthZ primitives. RoleAssignmentService and the Relationships API from the AuthZ team (OB2.8.3 in the delivery roadmap). - Closed-by-default design decision. #599683 (closed). - Organizations Universal Onboarding (OB2.1). Must expose the Resource Access entry point to the AR admin persona.