Project access tokens

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

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.

On GitLab.com, project access tokens require a Premium or Ultimate subscription. During a trial, you are limited to one project access token.

On GitLab Self-Managed and GitLab Dedicated, project access tokens are available with any license.

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:

On the top bar, select Search or go to and find your project.
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

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:

On the top bar, select Search or go to and find your project.
Select Settings > Access tokens.
Select Add new token.
In Token name, enter a name. The token name is visible to any user with permissions to view the project.
Optional. In Token description, enter a description for the token.
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.
Select a role for the token.
Select one or more project access token scopes.
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 tokens are treated as internal users. If an internal user creates a project access token, that token can access all projects that have visibility level set to Internal.

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.

If you have enabled external authorization, personal access tokens cannot access container or package registries. To restore access, turn off external authorization.

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.

This action cannot be undone. Tools that rely on a rotated access token will stop working until you reference your new token.

To rotate a project access token:

On the top bar, select Search or go to and find your project.
Select Settings > Access tokens.
For the relevant token, select Rotate ( ).
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.

This action cannot be undone. Tools that rely on a revoked access token will stop working until you add a new token.

To revoke a project access token:

On the top bar, select Search or go to and find your project.
Select Settings > Access tokens.
For the relevant token, select Revoke ( ).
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

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 check every day at 1:00 AM UTC to identify project access tokens that are expiring in the near future. Members of the project with the Maintainer or Owner role are notified by email when these tokens expire in a certain number of days. The number of days differs depending on the version of GitLab:

In GitLab 17.6 and later, project maintainers and owners are notified by email when the check identifies their project access tokens as expiring in the next 60 days. An additional email is sent when the check identifies their project access tokens as expiring in the next 30 days.
Project maintainers and owners are notified by email when the check identifies their project access tokens as expiring in the next seven days.
In GitLab 17.7 and later, project members who have inherited the Owner or Maintainer role due to the project belonging to a group can also receive notification emails. You can enable this by changing:
- The group setting in any of the parent groups of the project.
- On GitLab Self-Managed, the instance setting.

Your expired access tokens are listed in the inactive project access tokens table until they are automatically deleted.

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.

Inactive token retention

Offering: GitLab Self-Managed, GitLab Dedicated

By default, GitLab deletes group and project access tokens and their token family 30 days after the last active token in the token family becomes inactive. This deletion removes all tokens in the token family, the associated bot user, and moves any bot contributions to a ghost user.