Limit credential exposure with fine-grained personal access tokens
Source: GitLab Blog
Personal access tokens (PATs) authenticate most of the automation that runs in GitLab. When a token is issued with a broad scope like api or read_api, it extends permissions across many projects and groups. Fine‑grained permissions for PATs, now in beta, let you scope a token to exactly the privileges the job requires — for example, read access to one project’s code instead of read access across every project the user can reach.
The case for narrowing PAT privileges
A maintainer on 20 projects might carry a single token that can read source, modify pipelines, pull from the container registry, and decrypt CI/CD variables across all those projects. The token is scoped to the user, not a specific task, so if it leaks, it exposes every project the user can touch.
Fine‑grained PATs let teams ensure that scope follows the task: a read‑only token issued for one project is read‑only on that project alone. When exposed, investigation and remediation start and end there. Fine‑grained PATs also join safeguards like lifetime limits and automatic revocation, which limit how long an attacker can misuse a stolen token.
What’s new
You can define a fine‑grained PAT along two dimensions:
- 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 the things developers automate against (Issues, Merge Requests, Pipelines, Repositories, Container Registry, and more), with Create, Read, Update, and Delete assigned independently for each resource.
Instead of one PAT that can do everything you can do, you issue one PAT per job, carrying exactly that job’s permission set. For example, a pipeline that pushes container images gets a token scoped to the Container Registry on a single project, with Create and Read only. If that token leaks, the blast radius is limited to one registry on one project, not your entire footprint.
The tokens table has been updated to make this auditable at a glance. Every token you’ve created (coarse or fine‑grained) shows the exact scopes and per‑resource permissions, so over‑privileged tokens are easier to spot during reviews.
Today’s coverage and future roadmap
- Fine‑grained PATs currently cover about 75 % of REST API endpoints.
- In the coming months we’ll add support for the remaining REST endpoints and expand GraphQL coverage.
Existing PATs continue working as before. During the beta you can create traditional and fine‑grained PATs side by side as you evaluate the new model.
Learn more and share feedback
Creating 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.
Additional resources
- Administrative controls and the full list of supported resources and permissions are documented in the fine‑grained personal access tokens documentation.
- Share your feedback in the roadmap epic to help shape future iterations.