Project access tokens

Project access tokens provide authenticated access to a specific project. They are similar to group access tokens and personal access tokens, but are scoped to the associated project rather than a group or user. You cannot use project access tokens to access resources in other projects, or to create other group, project, or personal access tokens.

You can use a project access token to authenticate:

• With the GitLab API.
• With Git over HTTPS. Use:
  • Any non-blank value as a username.
  • The project access token as the password.

Prerequisites:

• The Maintainer or Owner role for the project.

View your access tokens

The project access tokens page displays information about your access tokens.

From this page, you can perform the following actions:

• Create, rotate, and revoke project access tokens.
• View all active and inactive project access tokens.
• View token information, including, scopes, assigned roles, and expiration dates.
• View usage information, including usage dates, and of the last five distinct connection IP addresses.
  GitLab periodically updates token usage information when the token performs a Git operation or authenticates an operation with the REST or GraphQL API. Token usage times are updated every 10 minutes, token usage IP addresses update every minute.

To view your project access tokens:

1. In the top bar, select Search or go to and find your project.
2. Select Settings > Access tokens.

Active and usable access tokens are stored in the Active project access tokens section. Expired, rotated, or revoked tokens are stored in the Inactive project access tokens section.

Create a project access token

To create a project access token:

1. In the top bar, select Search or go to and find your project.
2. Select Settings > Access tokens.
3. Select Add new token.
4. In Token name, enter a name. The token name is visible to any user with permissions to view the project.
5. Optional. In Token description, enter a description for the token.
6. In Expiration date, enter an expiry date for the token.
   • The token expires at midnight UTC on that date.
   • If you do not enter a date, the expiry date is set to 365 days from today.
   • By default, the expiry date cannot be more than 365 days from today. On GitLab 17.6 and later, administrators can modify the maximum lifetime of access tokens.
7. Select a role for the token.
8. Select one or more project access token scopes.
9. 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 cannot view it again.

All project access tokens inherit the default prefix setting configured for personal access tokens.

Project access token scopes

Scopes define the actions available when you authenticate with a project access token.

Scope	Description
api	Grants complete read and write access to the scoped project API, including the container registry, the dependency proxy, and the package registry.
read_api	Grants read access to the scoped project API, including the package registry.
read_registry	Grants read access (pull) to container registry images if the project is private and authorization is required. Available only when the container registry is enabled.
write_registry	Grants write access (push) to the container registry. To push images, you must include the read_registry scope. Available only when the container registry is enabled.
read_repository	Grants read access (pull) to the repository in the project.
write_repository	Grants read and write access (pull and push) to the repository in the project.
create_runner	Grants permission to create runners in the project.
manage_runner	Grants permission to manage runners in the project.
ai_features	Grants 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.
k8s_proxy	Grants permission to perform Kubernetes API calls using the agent for Kubernetes in the project.
self_rotate	Grants permission to rotate this token using the personal access token API. Does not allow rotation of other tokens.

Rotate a project access token

Rotate a token to create a new token with the same permissions and scope as the original. The original token becomes inactive immediately, and GitLab retains both versions for audit purposes. You can view both active and inactive tokens on the access tokens page.

On GitLab Self-Managed and GitLab Dedicated, you can modify the retention period for inactive tokens.

To rotate a project access token:

1. In the top bar, select Search or go to and find your project.
2. Select Settings > Access tokens.
3. For the relevant token, select Rotate ( ).
4. In the confirmation dialog, select Rotate.

Revoke a project access token

Revoke a token to immediately invalidate it and prevent further use. Revoked tokens are not deleted immediately, but you can filter token lists to show only active tokens. By default, GitLab deletes revoked group and project access tokens after 30 days. For more information, see inactive token retention.

To revoke a project access token:

1. In the top bar, select Search or go to and find your project.
2. Select Settings > Access tokens.
3. For the relevant token, select Revoke ( ).
4. In the confirmation dialog, select Revoke.

Access token expiration

Whether your existing project access tokens have expiry dates automatically applied depends on what GitLab offering you have, and when you upgraded to GitLab 16.0 or later:

• On GitLab.com, during the 16.0 milestone, existing project access tokens without an expiry date were automatically given an expiry date of 365 days later than the current date.
• On GitLab Self-Managed, if you upgraded from GitLab 15.11 or earlier to GitLab 16.0 or later:
  • On or before July 23, 2024, existing project access tokens without an expiry date were automatically given an expiry date of 365 days later than the current date. This change is a breaking change.
  • On or after July 24, 2024, existing project access tokens without an expiry date did not have an expiry date set.

On GitLab Self-Managed, if you do a new install of one of the following GitLab versions, your existing project access tokens do not have expiry dates automatically applied:

• 16.0.9
• 16.1.7
• 16.2.10
• 16.3.8
• 16.4.6
• 16.5.9
• 16.6.9
• 16.7.9
• 16.8.9
• 16.9.10
• 16.10.9
• 16.11.7
• 17.0.5
• 17.1.3
• 17.2.1

Project access token expiry emails

GitLab runs a daily check at 1:00 AM UTC to identify project access tokens that expire soon. Direct members with the Owner or Maintainer role are notified by email seven days before a token expires. In GitLab 17.6 and later, notifications are also sent 30 and 60 days before a token expires.

In GitLab 17.7 and later, members with an inherited Owner or Maintainer role can also receive these emails. You can configure this for every group and project on the GitLab instance or a specific parent group. If applied to a parent group, this setting is inherited by all descendant groups and projects.

Expired tokens appear in the inactive project access tokens section until they’re automatically deleted. On GitLab Self-Managed, you can modify this retention period.

Bot users for projects

When you create a project access token, GitLab creates a bot user and associates it with the token.

Bot users have the following properties:

• They are granted permissions that correspond with the role and scope of the associated access token.
• They are members of the project, but cannot be removed from the project or added directly to any other groups or projects.
• They are non-billable users and do not count towards your license limit.
• Their contributions are associated with the bot user account.
• When removed, their contributions are moved to a ghost user.

When the bot user is created, the following attributes are defined:

Attribute	Value	Example
Name	The name of the associated access token.	Main token - Read registry
Username	Generated in this format: project_{project_id}_bot_{random_string}	project_123_bot_4ffca233d8298ea1
Email	Generated in this format: project_{project_id}_bot_{random_string}@noreply.{Gitlab.config.gitlab.host}	project_123_bot_4ffca233d8298ea1@noreply.example.com

Restrict the creation of project access tokens

To limit potential abuse, you can restrict users from creating access tokens for projects in a top-level group. Any existing tokens remain valid until they expire or are manually revoked.

For more information, see restrict the creation of group and project access tokens.

Related topics

• Personal access tokens
• Group access tokens
• Project access tokens API