Project access tokens

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

Version history

• Introduced for trial subscriptions in GitLab 16.1.

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

Version history

• In GitLab 16.0 and earlier, token usage information is updated every 24 hours.
• The frequency of token usage information updates changed in GitLab 16.1 from 24 hours to 10 minutes.
• Ability to view IP addresses introduced in GitLab 17.8 with a flag named pat_ip. Enabled by default in 17.9.
• Ability to view IP addresses made generally available in GitLab 17.10. Feature flag pat_ip removed.

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.

  Note

  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

Version history

• Ability to create non-expiring project access tokens was removed in GitLab 16.0.
• Maximum allowable lifetime limit extended to 400 days in GitLab 17.6 with a flag named buffered_token_expiration_limit. Disabled by default.
• Project access token description introduced in GitLab 17.7.

[!flag] The availability of the extended maximum allowable lifetime limit is controlled by a feature flag. For more information, see the history.

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

Version history

• 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.
• self_rotate introduced in GitLab 17.9. Enabled by default.

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

Version history

• Ability to view expired and revoked tokens introduced in GitLab 17.3 with a flag named retain_resource_access_token_user_after_revoke. Disabled by default.
• Ability to view expired and revoked tokens until they are automatically deleted generally available in GitLab 17.9. Feature flag retain_resource_access_token_user_after_revoke removed.

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 ({retry}).
4. In the confirmation dialog, select Rotate.

Revoke a project access token

Version history

• Ability to view expired and revoked tokens introduced in GitLab 17.3 with a flag named retain_resource_access_token_user_after_revoke. Disabled by default.
• Ability to view expired and revoked tokens until they are automatically deleted generally available in GitLab 17.9. Feature flag retain_resource_access_token_user_after_revoke removed.

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 ({remove}).
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

Version history

• 60 and 30 day expiry notifications introduced in GitLab 17.6 with a flag named expiring_pats_30d_60d_notifications. Disabled by default.
• 60 and 30 day notifications generally available in GitLab 17.7. Feature flag expiring_pats_30d_60d_notifications removed.
• Notifications to inherited group members introduced in GitLab 17.7 with a flag named pat_expiry_inherited_members_notification. Disabled by default.
• Feature flag pat_expiry_inherited_members_notification enabled by default in GitLab 17.10.
• Feature flag pat_expiry_inherited_members_notification removed in GitLab 17.11

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

Version history

• Changed in GitLab 17.2 with a flag named retain_resource_access_token_user_after_revoke. Disabled by default. When enabled new bot users are made members with no expiry date and, when the token is later revoked or expires, the bot user is retained for 30 days.
• Inactive bot users retention is generally available in GitLab 17.9. Feature flag retain_resource_access_token_user_after_revoke removed.

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}	[email protected]

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