Skip to content

GitLab

Project access tokens

NOTE: Project access tokens are supported for self-managed instances on Free and above. They are also supported on GitLab SaaS Premium and above (excluding trial licenses). Self-managed Free instances should review their security and compliance policies with regards to user self-enrollment and consider disabling project access tokens to lower potential abuse.

WARNING: This feature might not be available to you. Check the version history note above for details.

Project access tokens are scoped to a project and can be used to authenticate with the GitLab API. You can also use project access tokens with Git to authenticate over HTTPS. If you are asked for a username when authenticating over HTTPS, you can use any non-empty value because only the token is needed.

Project access tokens expire on the date you define, at midnight UTC.

For examples of how you can use a project access token to authenticate with the API, see the following section from our API Docs.

Creating a project access token

  1. Log in to GitLab.
  2. Navigate to the project you would like to create an access token for.
  3. In the Settings menu choose Access Tokens.
  4. Choose a name and optional expiry date for the token.
  5. Choose a role for the token.
  6. Choose the desired scopes.
  7. Click the Create project access token button.
  8. Save the project access token somewhere safe. Once you leave or refresh the page, you don't have access to it again.

Project bot users

Project bot users are GitLab-created service accounts and do not count as licensed seats.

For each project access token created, a bot user is created and added to the project with the specified level permissions.

For the bot:

  • The name is set to the name of the token.
  • The username is set to project_{project_id}_bot for the first access token, such as project_123_bot.
  • The username is set to project_{project_id}_bot{bot_count} for further access tokens, such as project_123_bot1.

API calls made with a project access token are associated with the corresponding bot user.

These bot users are included in a project's Project information > Members list but cannot be modified. Also, a bot user cannot be added to any other project.

  • The username is set to project_{project_id}_bot for the first access token, such as project_123_bot.
  • The username is set to project_{project_id}_bot{bot_count} for further access tokens, such as project_123_bot1.

When the project access token is revoked the bot user is deleted and all records are moved to a system-wide user with the username "Ghost User". For more information, see Associated Records.

Revoking a project access token

At any time, you can revoke any project access token by clicking the respective Revoke button in Settings > Access Tokens.

Limiting scopes of a project access token

Project access tokens can be created with one or more scopes that allow various actions that a given token can perform. The available scopes are depicted in the following table.

Scope Description
api Grants complete read/write access to the scoped project API, including the Package Registry.
read_api Grants read access to the scoped project API, including the Package Registry.
read_registry Allows read-access (pull) to container registry images if a project is private and authorization is required.
write_registry Allows write-access (push) to container registry.
read_repository Allows read-only access (pull) to the repository.
write_repository Allows read-write access (pull, push) to the repository.

Enable or disable project access token creation

Introduced in GitLab 13.11.

You may enable or disable project access token creation for all projects in a group in Group > Settings > General > Permissions, LFS, 2FA > Allow project access token creation. Even when creation is disabled, you can still use and revoke existing project access tokens. This setting is available only on top-level groups.