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.
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.
Read original(opens in new tab)