A leaked personal access token shouldn't expose every project its owner can reach. Fine-grained PATs scope each token’s permissions to the job. (opens in new tab)
Fine-grained personal access tokens (PATs) reduce credential exposure by limiting each token to only the projects, groups, resources, and actions required for a specific task. GitLab’s beta lets users replace broad `api` or `read_api` tokens with narrowly scoped permissions, reducing the impact of leaks. The feature is not yet recommended for production because coverage is still incomplete. ## Why Narrow PAT Privileges - Broad, user-scoped tokens can access every project the user can reach. - A leaked token might expose source code, pipelines, container images, or CI/CD variables across many projects. - Fine-grained tokens limit both access and potential remediation to the affected project or resource. - They complement lifetime limits and automatic revocation. ## How Fine-Grained Tokens Work - Scope access by location: - Personal projects - All projects and groups where the user is a member - Specifically selected projects and groups - Assign independent Create, Read, Update, and Delete permissions. - Supported resources include Issues, Merge Requests, Pipelines, Repositories, and Container Registry. - Example: a container-publishing pipeline can receive Create and Read access only to one project’s registry. ## Auditing and Beta Coverage - The token management table displays scopes and per-resource permissions for all tokens. - This makes over-privileged credentials easier to identify during reviews. - Fine-grained PATs currently support about 75% of REST API endpoints. - GitLab plans to add remaining REST endpoints and expand GraphQL support. - Existing traditional PATs continue working alongside fine-grained tokens during the beta. ## Getting Started - Go to **User Settings → Personal Access Tokens**. - Select **Fine-grained token** when generating a token. - Choose the permitted projects or groups and assign resource permissions. - GitLab recommends avoiding fine-grained PATs in production until general availability. Teams should begin evaluating fine-grained tokens for automation and adopt one token per job, with the smallest practical scope. Feedback during the beta will help shape broader endpoint coverage and future improvements.