Project access tokens

Version history

You can use a project access token to authenticate:

  • With the GitLab API.
  • With Git, when using HTTP Basic Authentication.

After you configure a project access token, you don’t need a password when you authenticate. Instead, you can enter any non-blank value.

Project access tokens are similar to group access tokens and personal access tokens, except they are associated with a project rather than a group or user.

You can use project access tokens:

  • On GitLab SaaS if you have the Premium license tier or higher. Project access tokens are not available with a trial license.
  • On self-managed instances of GitLab, with any license tier. If you have the Free tier:

Project access tokens inherit the default prefix setting configured for personal access tokens.

Create a project access token

To create a project access token:

  1. On the top bar, select Menu > Projects and find your project.
  2. On the left sidebar, select Settings > Access Tokens.
  3. Enter a name. The token name is visible to any user with permissions to view the project.
  4. Optional. Enter an expiry date for the token. The token will expire on that date at midnight UTC.
  5. Select a role for the token.
  6. Select the desired scopes.
  7. Select Create project access token.

A project access token is displayed. Save the project access token somewhere safe. After you leave or refresh the page, you can’t view it again.

Revoke a project access token

To revoke a project access token:

  1. On the top bar, select Menu > Projects and find your project.
  2. On the left sidebar, select Settings > Access Tokens.
  3. Next to the project access token to revoke, select Revoke.

Scopes for a project access token

The scope determines the actions you can perform when you authenticate with a project access token.

Scope Description
api Grants complete read and 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 the Container Registry images if a project is private and authorization is required.
write_registry Allows write access (push) to the Container Registry.
read_repository Allows read access (pull) to the repository.
write_repository Allows read and write access (pull and push) to the repository.

Enable or disable project access token creation

Introduced in GitLab 13.11.

To enable or disable project access token creation for all projects in a top-level group:

  1. On the top bar, select Menu > Groups and find your group.
  2. On the left sidebar, select Settings > General.
  3. Expand Permissions and group features.
  4. Under Permissions, turn on or off Allow project and group access token creation.

Even when creation is disabled, you can still use and revoke existing project access tokens.

Bot users for projects

Version history

Bot users for projects are GitLab-created service accounts. Each time you create a project access token, a bot user is created and added to the project. These bot users do not count as licensed seats.

The bot users for projects have permissions that correspond with the selected role and scope of the project access token.

  • The name is set to the name of the token.
  • The username is set to project_{project_id}_bot for the first access token. For example, project_123_bot.
  • The email is set to project{project_id}_bot@noreply.{Gitlab.config.gitlab.host}. For example, project123_bot@noreply.example.com.
  • For additional access tokens in the same project, the username is set to project_{project_id}_bot{bot_count}. For example, project_123_bot1.
  • For additional access tokens in the same project, the email is set to project{project_id}_bot{bot_count}@noreply.{Gitlab.config.gitlab.host}. For example, project123_bot1@noreply.example.com.

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

Bot users for projects:

  • Are included in a project’s member list but cannot be modified.
  • Cannot be added to any other project.

When the project access token is revoked:

  • The bot user is deleted.
  • All records are moved to a system-wide user with the username Ghost User. For more information, see associated records.