## Executive Summary GitLab will offer fine-grained permissions for Personal Access Tokens, allowing users to create tokens with specific, limited access to only the resources and operations they need. This new capability replaces the previous broad scopes like `read_api` and `api` with granular permissions that can be restricted to specific projects and groups, significantly reducing the security blast radius if a token is compromised. Users can now apply the principle of least privilege to their automation and integrations by selecting precise combinations of read and write for different resource types including repositories, issues, pipelines, and more. --- ## Current Status See parent epic: https://gitlab.com/groups/gitlab-org/-/epics/18177#current-status+ --- ## General Availability Scope ### User Experience * I can view my token with its selected boundaries and fine-grained permissions under my user account. * I can enforce that my top-level group only allows granular PATs to access resources within subgroups and projects. * There is 40% of GraphQL resources covered by permissions during selection. * There is 75% of GraphQL resources covered by permissions during selection. * There is 100% of REST and GraphQL resources covered by permissions during selection. [(Wave 4)](https://gitlab.com/gitlab-org/gitlab/-/issues/572694). Instance level resources will be evaluated case by case [(Concluded discussion)](https://gitlab.com/gitlab-org/gitlab/-/issues/576069#note_2814026592) * I can view a token with its selected boundaries and fine-grained permissions under the credential inventory. * As a user, when I view the documentation for a specific API endpoint, GraphQL query or GraphQL mutation, I can see their required permissions. (Dependency: API Team) * I can use a template to quickly prefill permissions to create a token [(Pending problem validation)](https://gitlab.com/gitlab-org/gitlab/-/issues/572290) ### Parity with Existing PAT Capabilities - [Support existing audit events for PATs](https://docs.gitlab.com/user/compliance/audit_event_types/#compliance-management) is supported - Support existing personal access token [endpoints](https://docs.gitlab.com/api/user_tokens/) - Include the following new attributes: - Model type: Legacy or fine-grained - Scope selection - List of resources and permissions ### Auto-generated Documentation As a user, when I view the documentation for a specific API endpoint, GraphQL query or GraphQL mutation, I can see their required permissions. ### Future Product Compatibility - Product groups must add resource policies to endpoints and GraphQL queries and mutations for their features so there is no future permission gap for granular PATs. - Tooling must exist so that when adding endpoints or GraphQL queries and/or mutations without permission requirements, pipelines will fail. - Available contribution documentation so product teams can add their features to granular PATs. ### Performance and Security - Meets GitLab performance readiness requirements - Threat model and testing completed by security team ### Success Metrics * Find metrics [here](https://gitlab.com/groups/gitlab-org/-/epics/18177#success-metrics) --- <details> <summary> ### Interlock Details </summary> ##### Engineering Assessment * Epic/Issue dependencies: https://gitlab.com/gitlab-com/content-sites/internal-handbook/-/merge_requests/7011 #### Dependencies - Team dependencies: None ##### DRIs - **PM**: @jrandazzo <!--also add as assignee to this epic--> - **EM**: @ajaythomasinc <!--also add as assignee to this epic--> - **UX/PDM**: @ipelaez1 @jmandell <!--also add as assignee to this epic--> - **Group(s)**: ~&quot;group::authorization&quot; <!--also add as label--> - **Engineering Owner**: @mmishaev - **Product Security:** @ggray-gitlab #### Initiative Driver - Product or Engineering? - [x] **Product-driven initiatives (P1/P2/P3)** - Customer-facing features or improvements driven by Product teams that require engineering resources and commitment - These initiatives require a Product Priority label (P1/P2/P3) - They may also receive GTM tier labels (T1/T2/T3) for external communication - [ ] **Engineering-driven initiatives (E1/E2/E3)** - Internal technical improvements that may not have customer-facing components - These initiatives require an Engineering Priority label (E1/E2/E3) - They have internal visibility only and are not externally communicated - Examples include: technical debt reduction, infrastructure improvements, refactoring, dependency upgrades #### </details>