Group access tokens

Group access tokens provide authenticated access to a group and its projects. They are similar to personal access tokens and project access tokens, but are attached to a group rather than a user or project. You cannot use group access tokens to create other group, project, or personal access tokens.

You can use a group access token to authenticate:

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

Prerequisites:

• The Owner role for the group.

View your access tokens

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

From this page, you can perform the following actions:

• Create, rotate, and revoke group access tokens.
• View all active and inactive group 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 group access tokens:

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

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

Create a group access token

With the UI

To create a group access token:

1. In the top bar, select Search or go to and find your group.
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 group.
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 group access token scopes.
9. Select Create group access token.

A group access token is displayed. Save the group access token somewhere safe. After you leave or refresh the page, you cannot view it again.

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

With the Rails console

If you are an administrator, you can create group access tokens in the Rails console:

1. Run the following commands in a Rails console:

   # Set the GitLab administration user to use. If user ID 1 is not available or is not an administrator, use 'admin = User.admins.first' instead to select an administrator.
   admin = User.find(1)
   
   # Set the group you want to create a token for. For example, group with ID 109.
   group = Group.find(109)
   
   # Create the group bot user. For further group access tokens, the username should be `group_{group_id}_bot_{random_string}` and email address `group_{group_id}_bot_{random_string}@noreply.{Gitlab.config.gitlab.host}`.
   random_string = SecureRandom.hex(16)
   service_response = Users::CreateService.new(admin, { name: 'group_token', username: "group_#{group.id}_bot_#{random_string}", email: "group_#{group.id}_bot_#{random_string}@noreply.#{Gitlab.config.gitlab.host}", user_type: :project_bot }).execute
   bot = service_response.payload[:user] if service_response.success?
   
   # Confirm the group bot.
   bot.confirm
   
   # Add the bot to the group with the required role.
   group.add_member(bot, :maintainer)
   
   # Give the bot a personal access token.
   token = bot.personal_access_tokens.create(scopes:[:api, :write_repository], name: 'group_token')
   
   # Get the token value.
   gtoken = token.token

2. Test if the generated group access token works:

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

      • Create an epic in 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.

Group access token scopes

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

Scope	Description
api	Grants complete read and write access to the scoped group and related project API, including the container registry, the dependency proxy, and the package registry.
read_api	Grants read access to the scoped group and related project API, including the package registry.
read_repository	Grants read access (pull) to all repositories in the group.
write_repository	Grants read and write access (pull and push) to all repositories in the group.
read_registry	Grants read access (pull) to container registry images if any project in the group 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_virtual_registry	Grants read access (pull) to container images through the dependency proxy. Available only when the dependency proxy is enabled.
write_virtual_registry	Grants read and write access (pull, push, and delete) to container images through the dependency proxy. Available only when the dependency proxy is enabled.
create_runner	Grants permission to create runners in the group.
manage_runner	Grants permission to manage runners in the group.
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 group.
self_rotate	Grants permission to rotate this token using the personal access token API. Does not allow rotation of other tokens.

Rotate a group 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 group access token:

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

Revoke a group 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 group access token:

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

Group access token expiry emails

GitLab runs a daily check at 1:00 AM UTC to identify group access tokens that expire soon. Direct members with the Owner 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, inherited members with the Owner role can also receive these emails. You can configure this for every group on the GitLab instance or a specific group. If applied to a parent group, this setting is inherited by all descendant groups and projects.

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

Bot users for groups

When you create a group 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 group and inherit membership in subgroups and projects, but cannot be 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: group_{group_id}_bot_{random_string}	group_123_bot_4ffca233d8298ea1
Email	Generated in this format: group_{group_id}_bot_{random_string}@noreply.{Gitlab.config.gitlab.host}	group_123_bot_4ffca233d8298ea1@noreply.example.com

Restrict the creation of group and project access tokens

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

To restrict the creation of access tokens:

1. In the top bar, select Search or go to and find your top-level group.
2. Select Settings > General.
3. Expand Permissions and group features.
4. Clear the Users can create group access tokens and project access tokens in this group checkbox.
5. Select Save changes.

Related topics

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