GitLab has introduced fine-grained personal access tokens (PATs) in beta, allowing developers to scope authentication to specific tasks and projects rather than granting broad permissions across the entire account.
Overview
Personal access tokens authenticate most automation in GitLab — CI/CD pipelines, API calls, container registry pushes, and more. Traditionally, a PAT with a scope like api or read_api extends permissions across every project and group the token owner can access. If that token leaks, an attacker gains the same reach as the user.
Fine-grained PATs, now in beta, let you define a token's scope along two dimensions: which projects or groups it can reach, and what it can do there. Instead of one token that can do everything you can do, you issue one token per job, carrying exactly that job's permission set.
What it does
You can define a fine-grained PAT by selecting:
- Where it can reach: personal projects only, all projects and groups you're a member of, or only the projects and groups you select.
- What it can do there: per-resource permissions across Issues, Merge Requests, Pipelines, Repositories, Container Registry, and more, with Create, Read, Update, and Delete assigned independently for each resource.
For example, a pipeline that pushes container images no longer needs an api-scoped token. It gets a token scoped to the Container Registry on a single project, with Create and Read permissions only. If that token leaks, the blast radius is one registry on one project, not your entire footprint.
Tradeoffs
GitLab advises against using fine-grained PATs in production workloads until general availability. The beta currently covers about 75% of REST API endpoints. Support for the remaining REST endpoints and expanded GraphQL coverage is planned for the coming months.
Existing PATs continue working as before. During the beta, you can create traditional and fine-grained PATs side by side.
How to create one
To create a fine-grained personal access token:
- Navigate to User Settings → Personal Access Tokens.
- Choose "Fine-grained token" from the Generate token dropdown.
- Define the scope (projects/groups and per-resource permissions).
The tokens table has been updated to show exact scopes and per-resource permissions for every token, making over-privileged tokens easier to spot during reviews.
Bottom line
Fine-grained PATs join existing safeguards like lifetime limits and automatic revocation. For teams practicing least-privilege automation, they provide a practical way to limit credential exposure to exactly what a job requires — and no more.