gitlab-org--gitlab-foss/doc/user/project/settings/project_access_tokens.md

stage	group	info	type
Manage	Access	To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments	reference, howto

Project access tokens

• Introduced in GitLab 13.0.
• Became available on GitLab.com in GitLab 13.5 for paid groups only.
• Feature flag removed in GitLab 13.5.
• Changed in GitLab 14.5. Default prefix added.

Project access tokens are similar to personal access tokens except they are attached to a project rather than a user. They can be used to:

• Authenticate with the GitLab API.
• Authenticate with Git using HTTP Basic Authentication. If you are asked for a username when authenticating, 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.
• Are supported for self-managed instances on Free tier and above. Free self-managed instances should:
  • Review their security and compliance policies with regards to user self-enrollment.
  • Consider disabling project access tokens to lower potential abuse.
• Are also supported on GitLab SaaS Premium and above (excluding trial licenses.)

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

NOTE: For GitLab.com and new self-managed instances, the default prefix is glpat-.

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

• Introduced in GitLab 13.0.
• Excluded from license seat use in GitLab 13.5.

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 email is set to project{project_id}_bot@example.com, for example project123_bot@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 acess tokens in the same project, the email is set to project{project_id}_bot{bot_count}@example.com, for example project123_bot1@example.com

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.

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.

Group access token workaround (FREE SELF)

NOTE: This section describes a workaround and is subject to change.

Group access tokens let you use a single token to:

• Perform actions at the group level.
• Manage the projects within the group.
• In GitLab 14.2 and later, authenticate with Git over HTTPS.

We don't support group access tokens in the GitLab UI, though GitLab self-managed administrators can create them using the Rails console.

For a demo of the group access token workaround, see Demo: Group Level Access Tokens.

Create a group access token

To create a group access token, run the following in a Rails console:

admin = User.find(1) # group admin
group = Group.find(109) # the group you want to create a token for
bot = Users::CreateService.new(admin, { name: 'group_token', username: "group_#{group.id}_bot", email: "group_#{group.id}_bot@example.com", user_type: :project_bot }).execute # create the group bot user
# for further group access tokens, the username should be group_#{group.id}_bot#{bot_count}, e.g. group_109_bot2, and their email should be group_109_bot2@example.com
bot.confirm # confirm the bot
group.add_user(bot, :maintainer) # add the bot to the group at the desired access level
token = bot.personal_access_tokens.create(scopes:[:api, :write_repository], name: 'group_token') # give it a PAT
gtoken = token.token # get the token value

Test if the generated group access token works:

1. Pass the group access token in the PRIVATE-TOKEN header to GitLab REST APIs. For example:

   • Create an epic on the group.
   • Create a project pipeline in one of the group's projects.
   • Create an issue in one of the group's projects.

2. Use the group token to clone a group's project using HTTPS.

Revoke a group access token

To revoke a group access token, run the following in a Rails console:

bot = User.find_by(username: 'group_109_bot') # the owner of the token you want to revoke
token = bot.personal_access_tokens.last # the token you want to revoke
token.revoke!