docs(remote): describe fine-grained token support

What does this MR do and why?

The GitLab Orbit docs said fine-grained personal access tokens are not supported. That changed when gitlab-org/gitlab!256556 (merged) merged: tokens with the new Orbit: Read permission on the User tab can call the REST API and MCP.

This MR replaces the "not supported" line with one short section. It says how to set up the token, what it reads, and which tokens get a 403. The REST and MCP pages link to it.

Relates to #992 (closed). Pairs with gitlab-org/gitlab!256556 (merged) (merged).

Testing

Vale, markdownlint, and prose lint pass. Each rule was verified end to end on a GDK VM with the Rails MR. 13 checks cover user, group, all-memberships, legacy, old-name, and MCP tokens.

Before, on the security page:

- REST API: a standard (legacy) personal access token with the `read_api` scope, sent as a
  Bearer token. Fine-grained personal access tokens are not supported.

After:

### Fine-grained personal access tokens

To use a fine-grained personal access token, on the **User** tab, select **GitLab Orbit** and the **Read** permission.
The permission covers the REST API and MCP.

- Results match what the token owner can access in GitLab.
  Other permissions on the token do not limit them.
- Group and project scopes are not supported.
  A token with only **Group and project access** gets a `403 Forbidden` response.
- Tokens created with the **Knowledge Graph: Read** or **GitLab Orbit MCP tool: Execute** permission get a `403 Forbidden` response.
  Create a new token.
- SAML SSO enforcement does not apply to personal access tokens.
  A token keeps working after the owner's SAML session expires.

Performance Analysis

  • This merge request does not introduce any performance regression. Docs only.
Agent context: long-form analysis, file-by-file walkthroughs, profiler output, alternatives considered

How the design landed. The full background is in the decision comment on #992. In short:

  • Matching Orbit results to every permission on a token was too costly. Three attempts closed: gitlab-org/gitlab!247199 (closed), gitlab-org/gitlab!253835 (closed), and !2409 (closed).
  • Orbit follows Global Search instead. The token check gates the endpoint, and results follow the owner's GitLab access.
  • A version that trimmed results to the token's selected groups was built, then dropped in authz review. Scopes gate endpoints, they do not filter results. Group-limited access moves to /groups/:id/orbit/* routes in #1324.
  • The old permission names stay defined as deprecated in Rails, pointing at nothing an Orbit route checks. Old tokens get a 403 from Orbit but stay valid and rotatable, so no data migration was needed.

Files.

  • docs/source/remote/security.md: the new section, and a link from the programmatic access list.
  • docs/source/remote/access/api.md and access/mcp.md: one link each, no repeated rules.
  • docs/design-documents/security.md: a token gateway section with the design rationale and prior-art permalinks.

Wording notes. Vale's orbit.StandaloneProductName rule rejects the resource label "Orbit" on its own. On the User tab, the GitLab Orbit category holds only that resource, so "select GitLab Orbit" is accurate. The old MCP permission's UI label came from its metadata name, "GitLab Orbit MCP tool".

Edited by Michael Angelo Rivera

Merge request reports

Loading
Loading