GitLab fine-grained personal access tokens, one action at a time

Ask GitLab what a classic personal access token may do and the answer is in the token’s own description: "scopes": ["read_api"]. Ask the same of a fine-grained token on GitLab 19.4 and you learn that it is fine-grained, and nothing else. Its scope list is the single value granular; what it may actually do is a grant of named permissions that, on 19.4, the token’s own endpoint does not even return.

That is a problem for any API client, and a sharp one for gitlab-mcp-server, which exposes GitLab’s API as tools for clients over the Model Context Protocol and has to tell each session which of its catalog actions that session’s token can run. This post is about how I made it answer that question before anything is sent to GitLab, and the merge requests to GitLab that came out of it.

What is a GitLab fine-grained personal access token?

A GitLab fine-grained personal access token holds a grant of named permissions, each applied at a boundary, instead of a list of scopes; it has been generally available since GitLab 19.2, and the grant cannot be changed after the token is created.

GitLab introduced these tokens as a beta in 18.10. A grant lists resources and permissions such as Project: Read, Merge Request: Approve or Pipeline: Read. The token creation page groups them on three tabs, Group and project, User and Global. Over the API, a grant is a list of scopes, each with an access level (personal_projects, all_memberships, selected_memberships, user or instance), its permissions, and for selected_memberships the projects or groups it covers.

GitLab’s fine-grained personal access tokens documentation describes two checks on every request: “The token has a permission for the operation, on the resource in the request path” and “You, as the token owner, can perform that operation.” The token’s scope list takes no part in it. GitLab’s create service writes scopes: [GRANULAR_SCOPE], granular: true on every fine-grained token, where GRANULAR_SCOPE is :granular.

On 19.4, the token’s own endpoint shows exactly that:

Two more facts shape everything below:

• A grant cannot be changed after the token is created. No route, mutation or settings page edits one, and rotating a token copies the old grant to the new token. A missing permission always means a new token.
• Organizations can require them. On GitLab Self-Managed, an administrator can stop users creating or rotating legacy tokens after a date; existing legacy tokens keep working until they expire. On GitLab.com, GitLab documents a setting that lets the Owner of a top-level group block legacy personal access tokens from the group’s resources after a date; they keep working outside the group. Enforcement was introduced in 18.11 behind feature flags and has been generally available on Self-Managed since 19.2, while the GitLab.com setting is still behind its flag. Service account, group and project access tokens are exempt.

REST tells you, GraphQL does not

On REST, a call outside the grant is explicit. Take a token granted Project: Read on a private project, but not Branch: Read, and list the project’s branches:

The route’s declaration says the same thing ahead of time: GET /projects/:id/repository/branches declares read_branch at the project boundary, and POST on the same path declares create_branch. The permission is named by its display label rather than the identifier a token is created with, but a client can at least tell its user what to grant. On a public project with a public repository, the branch list is served without Branch: Read, because GitLab grants a fine-grained token every permission an anonymous visitor holds there.

GraphQL is silent. GitLab denies a fine-grained token at every GraphQL type that declares no fine-grained directive, as a comment in granular_scope_authorization.rb puts it: “if no gPAT directives are defined, granular tokens deny access while legacy tokens fall through to their existing authorization” (GitLab’s source calls a fine-grained token a granular PAT, or gPAT). A denied object is answered as null, and a list drops it, with no error. Where the field cannot be null, the null spreads to the nearest parent that can be null, and the only error is GraphQL’s generic “Cannot return null for non-nullable field”, which says nothing about the token.

Mutations are the exception, and never silent: one that declares a permission the grant lacks is answered with the field null and the same sentence REST gives, in errors, and one that declares nothing with GitLab’s generic “The resource that you are attempting to access does not exist or you don’t have permission to perform this action”. The silent cases are the types.

The clearest case is an epic. GitLab declares WorkItem at the project boundary only, and an epic is a group’s work item, so no boundary resolves for it. A token granted Work Item: Read and Work Item: Update on the group reads the epic as null, while a classic token reads it:

query { workItem(id: "gid://gitlab/WorkItem/<epic>") { title } }

A group’s epic list does the same with nodes: []. Another GitLab user reported exactly that in gitlab-org/gitlab#630483 in September, noting that the failure is silent and easy to misread as no matching epics. The same pattern shows up on namespace(fullPath:), which answers null, and on a project’s branch rules, which come back without their items.

This is not a handful of types. GitLab keeps its own list of what still has no declaration, config/authz/graphql/authorization_todo.txt: 862 types and 61 mutations at GitLab 19.4.1, and 859 and 42 on master on 9 October 2026. GitLab is working through it, and its planning issue gitlab-org/gitlab#631631 describes the same behavior from its side: an object type without the directive “resolves to nil for granular tokens, nulling query data or erroring mutations.”

Answering it ahead of time, per action

So I made the server answer it before the first request. ADR-0024 splits the answer into three facts with three owners, joined by a generator:

• What each action requests is the repository’s, derived from the handlers.
• What GitLab demands of each route and GraphQL element is GitLab’s, recorded from a booted GitLab.
• How an action’s requests combine (all of them, one of several, or one only with some input) is the handler author’s, declared at the call site.

The ADR rejects the alternative of writing the permission by hand on each action: “1098 literals across some 180 packages”, rewritten whenever GitLab renames a permission. GitLab 19.0 renamed 66 permissions in existing tokens (read_user_ssh_key became read_ssh_key, for one), and 19.4.1 still lists 71 permissions as deprecated.

What each action sends

cmd/gen_action_grants walks every catalog action’s handlers and the client-go methods they call, and writes what each action sends to action-requests.json. Of the 1,098 actions, 76 touch GraphQL. branch.create, for example, sends one mandatory POST /projects/:id/repository/branches; custom_emoji.create sends the createCustomEmoji mutation and selects createCustomEmoji.customEmoji.

What GitLab declares

The second input is the record taken from a booted GitLab. What building a GitLab MCP server taught me about GitLab’s API describes it; in short, a command in the repository, cmd/gen_api_live, boots a released gitlab-ee image and asks the loaded application, rather than parsing its source or its OpenAPI document. Since its schema version 4 the record also carries authorization: at 19.4.1, 1,892 of the 2,152 REST routes declare a permission, and the rest either declare a reason to skip the check or sit on GitLab’s todo list; on GraphQL, 260 object types and 645 mutations declare one. What they declare are GitLab’s internal permissions, and a token is granted them through GitLab’s assignable permissions, 857 at 19.4.1, each covering one or more of them (Pipeline: Update covers cancel_pipeline, for one).

The join, and the answer spine

For REST, an action’s requirement is its routes’ declarations. GraphQL needs one more idea, because a denied position does not fail the request: it becomes null, and what that null costs depends on where it lands. The generator judges each document along its answer spine, the chain of objects the answer hangs from. It starts at the root field (for a mutation, at the first object its payload selects) and follows the one object each position selects, as long as nothing but connection framing is selected beside it. A position that declares nothing is fatal when its null lands on the spine, and off the spine it only empties a field. A declared position the grant does not cover is judged the same way: on the spine it withholds the action, and off it the field comes back empty, which is what “depending on the grant” means below.

Two of the server’s actions show both outcomes:

A write can lose its answer the same way. custom_emoji.create sends a mutation that declares Custom Emoji: Create at the group, but its payload selects CustomEmoji, which declared nothing at 19.4.1. So the emoji is created and the answer is null: the reference page says “the write commits and its answer is lost”. GitLab has since declared CustomEmoji in gitlab-org/gitlab!260586, another contributor’s merge request for 19.5, merged on 8 October 2026, which is a good illustration that the table moves with GitLab’s releases.

What the walk cannot read is declared by hand with a category and a reason, and a declaration that answers nothing is itself a finding. The output is a table compiled into the server (table_gen.go), generated and checked in CI against the record, plus a gitlab-mcp-server fine-grained permissions reference page with one row per action: what it needs in GitLab’s words, at which boundary, and which parts may be served empty.

58 actions out of reach of every fine-grained token at GitLab 19.4.1

The join finds all 58 among the GraphQL actions, and each is out of reach for one of four reasons:

By area they are 15 epic actions, 12 work item actions (with their saved views and types), 12 achievements, 3 custom emoji, 2 CI catalog, 2 target branch rules, 1 branch rules and 11 security actions. Another 10 actions are served with parts that may be empty (vulnerability reads and writes, Terraform state, two epic note updates). On master on 9 October, 54 of the 58 are still blocked by a type or mutation on GitLab’s pending list; the three custom emoji actions are not, since CustomEmoji has left it, and group.epic_create waits on gitlab-org/gitlab!259765.

What a client is told

The server learns the token’s kind from GET /personal_access_tokens/self. A scope list of exactly ["granular"] is read as unknown authority, never as read-only, so a fine-grained token is not narrowed like a read_api token.

Then one of two phases applies. The server falls back to phase A when any of these holds: the token cannot read its own grant (no Personal Access Token: Read), there is no readable version (no Metadata: Read), the instance runs a release other than 19.4 (the prerelease of the next minor, 19.5.0-pre, which GitLab.com reports, is the one exception, below), the grant names a permission the table does not know, or the grant is larger than 1 MiB or 1,000 scopes or holds a scope the server cannot read without guessing. If GitLab does not answer the first read of the grant or the version, the session also starts in phase A, until a revalidation reads them.

GitLab.com reports 19.5.0-pre, the minor after the recorded one, so a session there is shown what its grant reaches at 19.4.1, and every call not withheld from all fine-grained tokens goes to GitLab, which has the last word on anything that changed in that milestone. The grant is re-read on every revalidation, every 15 minutes by default, and a failed re-read keeps the previous answer. For anyone running the HTTP mode for a team: the grant is never a cache key. It is a value the caller mints, so one server serves classic and fine-grained credentials and narrows per request.

In phase B, when the grant does not reach an action, the answer names the permission in the words of GitLab’s token creation page:

action "branch.create" exists but this fine-grained personal access token was not granted what it needs: the project permission [Branch: Create], as GitLab 19.4.1 declares it. Create a fine-grained token that grants it, or use a classic token with the api scope (an existing one, on an instance that no longer lets you create them), where the group does not refuse classic tokens.

When no fine-grained token can reach it at that release, the answer says why and points to the way out:

action "custom_emoji.list" exists but is not available to a fine-grained personal access token: GitLab 19.4.1 declares no fine-grained permission on the GraphQL type CustomEmoji this action reads, and removes the items from such a list. Use a classic personal access token with read_api for reads or api for writes (an existing one, on an instance that no longer lets you create them), where the group does not refuse classic tokens.

Both close with one more sentence, telling the client not to conclude that the feature is missing, since the action exists and only the credential cannot run it. On the default surface, where the client calls gitlab_execute_action, each text is prefixed with gitlab_execute_action:. The classic way out is qualified for both forms of enforcement, because on an enforcing instance a client may not be able to create a classic token, and in an enforcing group one may not work. A served answer that GitLab may leave partly empty carries a note that names the empty part as a GraphQL selection, vulnerability { issueLinks { nodes } } for example, and says “Empty there does not mean there is nothing.”

All of this ships in gitlab-mcp-server 3.2.0, released on 9 October 2026. On 3.0.0 and 3.1.0, the server read the scope granular as one that cannot write, so a fine-grained token granted Personal Access Token: Read was served only its read-only actions, while one without it, whose scopes could not be read, was served every action and GitLab judged each call. HTTP mode with OAuth refused both at the door.

Classic tokens, from the same record

The same derived requests answer the classic question too. GitLab’s rule is read_api for a REST GET or HEAD and a GraphQL query, api for anything else, with declared exceptions.

ADR-0026 followed from seven actions on which two questions disagreed, whether the action writes and which scope GitLab demands: template.lint is a read sent as a POST, which GitLab refuses to read_api, while package.download sends only GETs but writes a file on the server’s machine, so it was withheld from a read_api token that GitLab serves it to. So a read_api token is now served what GitLab accepts from it: 525 of the 1,098 actions, 61 of them in the administration groups the server lists only to a token that also carries admin_mode. Before, it was served the actions the catalog classifies as read-only. How GitLab refuses a token that lacks a classic scope, and the challenge it does not send, is in the previous post.

Fixing the API it reads

The server reads a token’s grant with two requests, because client-go does not model the grant and on 19.4 GET /personal_access_tokens/self does not present it: it asks the self endpoint what the token is, then GET /personal_access_tokens/:id for the grant, on GitLab.com as well. That gap, and a few around it, became the merge requests below: eight I opened in gitlab-org/gitlab from 5 to 8 October 2026, and one in client-go, open since 27 September:

The first of them answers the question this post opened with: from GitLab 19.5, and on GitLab.com since 7 October, a fine-grained token can read its own grant from the self endpoint. What is still open is the administrator route, group work items, the validation check, client-go’s structs, and the GraphQL declarations themselves, which are GitLab’s own pending list and the reason the 58 exist.

My thanks to the GitLab reviewers who took these on and merged five of them within days.

Create a token for gitlab-mcp-server

The gitlab-mcp-server fine-grained tokens guide has every detail; this is the short path.

1. Decide what the client should do

Look the actions up on the fine-grained permissions reference, or on the action’s entry in the gitlab-mcp-server tool reference, whose “Fine-grained token” line names what it needs: for branch.create, “Branch: Create at project”.

2. Generate a fine-grained token in GitLab

In GitLab, select your avatar, then Edit profile, Access > Personal access tokens, and Generate token > Fine-grained token. Give it a name, a description and an expiry, at most 365 days by default. If you add project or group resources, pick an option under Group and project access, then use the Group and project, User and Global tabs under Add resource permissions. Add the permissions of steps 3 and 4 before you submit the form.

3. Add the startup permissions

4. Add the work permissions

Grant what the actions need, at the project or the group. Some common sets, from the guide:

Some pairings are GitLab’s: a note on an issue, or on a merge request, is created with Work Item: Create, and a merge request discussion with Merge Request: Create, because that is what the routes declare at 19.4.1. Grant everything now: the grant cannot be changed later. Then select Generate token and store the token: it is shown once.

5. Configure the server

Set GITLAB_URL and GITLAB_TOKEN for stdio, or send the token per request in HTTP mode. Nothing else is needed; the server detects the token kind. In phase B the session lists only what the grant reaches, and the 58 actions above are withheld from every fine-grained token with the reason and the classic-token way out.

Closing

The per-action table exists because the server treats GitLab’s own declarations as the source of truth and checks itself against a booted GitLab, and that same habit is how I found the gaps in GitLab’s token API above. The previous post tells that story for the rest of the API: the recorded GitLab, the request inventory, the pinned GraphQL schema, and how a register of findings turned into merge requests to GitLab.