1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
|
---
stage: Manage
group: Authentication & Authorization
info: "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"
type: reference, howto
---
# 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](../../../api/index.md#personalprojectgroup-access-tokens).
- In [GitLab 14.2](https://gitlab.com/gitlab-org/gitlab/-/issues/330718) and later, authenticate with Git over HTTPS.
After you configure a group access token, you don't need a password when you authenticate.
Instead, you can enter any non-blank value.
Group access tokens are similar to [project access tokens](../../project/settings/project_access_tokens.md)
and [personal access tokens](../../profile/personal_access_tokens.md), except they are
associated with a group rather than a project or user.
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](https://about.gitlab.com/free-trial/).
- 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](../../admin_area/settings/sign_up_restrictions.md#disable-new-sign-ups).
- Consider [disabling group access tokens](#enable-or-disable-group-access-token-creation) to
lower potential abuse.
Group access tokens inherit the [default prefix setting](../../admin_area/settings/account_and_limit_settings.md#personal-access-token-prefix)
configured for personal access tokens.
## Create a group access token using UI
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214045) in GitLab 14.7.
To create a group access token:
1. On the top bar, select **Menu > Groups** and find your group.
1. On the left sidebar, select **Settings > Access Tokens**.
1. Enter a name.
1. Optional. Enter an expiry date for the token. The token will expire on that date at midnight UTC.
1. Select a role for the token.
1. Select the [desired scopes](#scopes-for-a-group-access-token).
1. 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.
## 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](../../../administration/operations/rails_console.md):
```ruby
# 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#{bot_count}. For example, group_109_bot2 and email address group_109_bot2@example.com.
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
# Confirm the group bot.
bot.confirm
# Add the bot to the group with the required role.
group.add_user(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
```
1. 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](../../../api/epics.md#new-epic) in the group.
- [Create a project pipeline](../../../api/pipelines.md#create-a-new-pipeline) in one of the group's projects.
- [Create an issue](../../../api/issues.md#new-issue) in one of the group's projects.
1. Use the group token to [clone a group's project](../../../gitlab-basics/start-using-git.md#clone-with-https)
using HTTPS.
## Revoke a group access token using the UI
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214045) in GitLab 14.7.
To revoke a group access token:
1. On the top bar, select **Menu > Groups** and find your group.
1. On the left sidebar, select **Settings > Access Tokens**.
1. 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](../../../administration/operations/rails_console.md):
```ruby
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.
| Scope | Description |
|:-------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `api` | Grants complete read and write access to the scoped group and related project API, including the [Package Registry](../../packages/package_registry/index.md). |
| `read_api` | Grants read access to the scoped group and related project API, including the [Package Registry](../../packages/package_registry/index.md). |
| `read_registry` | Allows read access (pull) to the [Container Registry](../../packages/container_registry/index.md) images if any project within a group is private and authorization is required. |
| `write_registry` | Allows write access (push) to the [Container Registry](../../packages/container_registry/index.md). |
| `read_repository` | Allows read access (pull) to all repositories within a group. |
| `write_repository` | Allows read and write access (pull and push) to all repositories within a group. |
## Enable or disable group access token creation
To enable or disable group access token creation for all sub-groups in a top-level group:
1. On the top bar, select **Menu > Groups** and find your group.
1. On the left sidebar, select **Settings > General**.
1. Expand **Permissions and group features**.
1. Under **Permissions**, turn on or off **Allow project and group access token creation**.
Even when creation is disabled, you can still use and revoke existing group access tokens.
## Bot users for groups
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](../../project/settings/project_access_tokens.md#bot-users-for-projects), but are added to groups instead of projects. For more information, see
[Bot users for projects](../../project/settings/project_access_tokens.md#bot-users-for-projects).
|