ContextQMD
Back to Gitlabhq

Access token scopes

doc/security/tokens/access_token_scopes.md

19.1.06.9 KB
Original Source

{{< details >}}

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

{{< history >}}

  • Personal access tokens can no longer access container or package registries introduced in GitLab 16.0.
  • k8s_proxy introduced in GitLab 16.4 with a flag named k8s_proxy_pat. Enabled by default.
  • Feature flag k8s_proxy_pat removed in GitLab 16.5.
  • read_service_ping introduced in GitLab 17.1. Personal access tokens only.
  • manage_runner introduced in GitLab 17.1.
  • self_rotate introduced in GitLab 17.9. Enabled by default.

{{< /history >}}

Scopes define what an access token can do at a specific organizational level. Each scope grants a specific set of permissions.

The token type determines a token's reach:

  • A personal access token can access all groups and projects available to the user.
  • A group access token can access the subgroups and projects in its group.
  • A project access token can access only its project.

To restrict a personal access token to specific resources and permissions, see fine-grained personal access tokens.

ScopeToken availabilityDescription
apiPersonal, group, projectGrants complete read and write access to the API for the token's scope. Includes the container registry, the dependency proxy, and the package registry. <sup>1</sup>
read_apiPersonal, group, projectGrants read access to the API for the token's scope. For a personal access token, includes the container registry and the package registry; for group and project access tokens, the package registry only.
read_repositoryPersonal, group, projectGrants read access (pull) to repositories for the token's scope: private projects for a personal access token, all repositories in the group for a group access token, or the repository in the project for a project access token. Uses Git-over-HTTP or the repository files API.
write_repositoryPersonal, group, projectGrants read and write access (pull and push) to repositories for the token's scope: private projects for a personal access token, all repositories in the group for a group access token, or the repository in the project for a project access token. Uses Git-over-HTTP. Does not support API authentication.
read_registryPersonal, group, projectGrants read access (pull) to container registry images when authorization is required. Available only when the container registry is enabled. The privacy condition differs by token type: it applies to a personal access token when a project is private, to a group access token when any project in the group is private, and to a project access token when the project is private.
write_registryPersonal, group, projectGrants write access (push) to container registry images. Available only when the container registry is enabled. For group and project access tokens, you must also include the read_registry scope to push images.
self_rotatePersonal, group, projectGrants permission to rotate this token. Cannot rotate other tokens. To rotate personal access tokens, see the personal access token API.
read_virtual_registryPersonal, groupGrants read access (pull) to container images through the dependency proxy. Available only when the dependency proxy is enabled. <sup>2</sup>
write_virtual_registryPersonal, groupGrants read and write access (pull, push, and delete) to container images through the dependency proxy. Available only when the dependency proxy is enabled. <sup>2</sup>
create_runnerPersonal, group, projectGrants permission to create runners for the token's scope.
manage_runnerPersonal, group, projectGrants permission to manage runners for the token's scope.
ai_featuresPersonal, group, projectGrants permission to perform API actions for GitLab Duo, the Code Suggestions API, and the GitLab Duo Chat API. Designed to work with the GitLab Duo Plugin for JetBrains. For all other extensions, see the individual extension documentation. Does not work for GitLab Self-Managed versions 16.5, 16.6, and 16.7. On GitLab Self-Managed and GitLab Dedicated, this scope is only available when GitLab Duo is enabled.
k8s_proxyPersonal, group, projectGrants permission to perform Kubernetes API calls through the agent for Kubernetes.
admin_modePersonalGrants permission to perform API actions when Admin Mode is enabled. Available only to administrators on GitLab Self-Managed instances.
read_service_pingPersonalGrants access to download the Service Ping payloads through the API when authenticated as an administrator.
sudoPersonalGrants permission to perform API actions as any user in the system, when authenticated as an administrator.
read_userPersonalGrants read-only access to the authenticated user's profile through the /user API endpoint, which includes username, public email, and full name. Also grants access to read-only API endpoints under /users.

[!warning] If you have turned on external authorization, personal and project access tokens cannot access container or package registries. To restore access, turn off external authorization.

Footnotes:

  1. For a personal access token, api also grants complete read and write access to the registry and repository through Git-over-HTTP. Group and project access tokens do not include this Git-over-HTTP clause.
  2. For a personal access token, the virtual registry scopes apply only when a project is private and authorization is required. Group access tokens carry no such condition.