Group access tokens

With group access tokens, you can use a single token to:

• Perform actions for groups.
• Manage the projects within the group.

You can use a group access token to authenticate:

• With the GitLab API.

• In GitLab 14.2 and later, authenticate with Git over HTTPS. Use:

  • Any non-blank value as a username.
  • The group access token as the password.

Group access tokens are similar to project access tokens and personal access tokens, except they are associated with a group rather than a project or user.

In self-managed instances, group access tokens are subject to the same maximum lifetime limits as personal access tokens if the limit is set.

WARNING: The ability to create group access tokens without expiry was deprecated in GitLab 15.4 and is planned for removal in GitLab 16.0. When this ability is removed, existing group access tokens without an expiry are planned to have an expiry added. The automatic adding of an expiry occurs on GitLab.com during the 16.0 milestone. The automatic adding of an expiry occurs on self-managed instances when they are upgraded to GitLab 16.0. This change is a breaking change.

You can use group access tokens:

• On GitLab SaaS if you have the Premium license tier or higher. Group access tokens are not available with a trial license.
• On self-managed instances of GitLab, with any license tier. If you have the Free tier:
  • Review your security and compliance policies around user self-enrollment.
  • Consider disabling group access tokens to lower potential abuse.

You cannot use group access tokens to create other group, project, or personal access tokens.

Group access tokens inherit the default prefix setting configured for personal access tokens.

Create a group access token using UI

• Introduced in GitLab 14.7.
• Introduced in GitLab 15.3, default expiration of 30 days and default role of Guest is populated in the UI.

To create a group access token:

1. On the top bar, select Main menu > Groups and find your group.
2. On the left sidebar, select Settings > Access Tokens.
3. Enter a name. The token name is visible to any user with permissions to view the group.
4. Optional. Enter an expiry date for the token. The token will expire on that date at midnight UTC. An instance-wide maximum lifetime setting can limit the maximum allowable lifetime in self-managed instances.
5. Select a role for the token.
6. Select the desired scopes.
7. 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 can't view it again.

WARNING: Group access tokens are treated as internal users. If an internal user creates a group access token, that token is able to access all groups that have visibility level set to Internal.

Create a group access token using Rails console

GitLab 14.6 and earlier doesn't support creating group access tokens using the UI or API. However, administrators can use a workaround:

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 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)
   bot = 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
   
   # 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.

Revoke a group access token using the UI

Introduced in GitLab 14.7.

To revoke a group access token:

1. On the top bar, select Main menu > Groups and find your group.
2. On the left sidebar, select Settings > Access Tokens.
3. Next to the group access token to revoke, select Revoke.

Revoke a group access token using Rails console

GitLab 14.6 and earlier doesn't support revoking group access tokens using the UI or API. However, administrators can use a workaround.

To revoke a group access token, run the following command 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!

Scopes for a group access token

The scope determines the actions you can perform when you authenticate with a group access token.

Enable or disable group access token creation

To enable or disable group access token creation for all subgroups in a top-level group:

1. On the top bar, select Main menu > Groups and find your group.
2. On the left sidebar, select Settings > General.
3. Expand Permissions and group features.
4. Under Permissions, turn on or off Users can create project access tokens and group access tokens in this group.

Even when creation is disabled, you can still use and revoke existing group access tokens.

Bot users for groups

Bot users for groups are GitLab-created service accounts. Each time you create a group access token, a bot user is created and added to the group. These bot users are similar to bot users for projects, except they are added to groups instead of projects. Bot users for groups:

• Do not count as licensed seats.
• Can have a maximum role of Owner for a group. For more information, see Create a group access token.
• Have a username set to group_{group_id}_bot_{random_string}. For example, group_123_bot_4ffca233d8298ea1.
• Have an email set to group_{group_id}_bot_{random_string}@noreply.{Gitlab.config.gitlab.host}. For example, group_123_bot_4ffca233d8298ea1@noreply.example.com.

All other properties are similar to bot users for projects.

Token availability

Group access tokens are only available in paid subscriptions, and not available in trial subscriptions. For more information, see the "What is included" section of the GitLab Trial FAQ.