| `access_level` | Integer | no | A valid access level. Default value is 40 (Maintainer). Other allowed values are 10 (Guest), 20 (Reporter), and 30 (Developer). |
| `access_level` | Integer | no | A valid access level. Default value is 40 (Maintainer). Other allowed values are 10 (Guest), 20 (Reporter), and 30 (Developer). |
| `expires_at` | Date | no | The token expires at midnight UTC on that date |
| `expires_at` | Date | no | The token expires at midnight UTC on that date |
@@ -42,7 +42,7 @@ Using the **Delete user and contributions** option may result
...
@@ -42,7 +42,7 @@ Using the **Delete user and contributions** option may result
in removing more data than intended. Please see [associated records](#associated-records)
in removing more data than intended. Please see [associated records](#associated-records)
below for additional details.
below for additional details.
### Associated Records
### Associated records
> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/7393) for issues in GitLab 9.0.
> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/7393) for issues in GitLab 9.0.
> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/10467) for merge requests, award emoji, notes, and abuse reports in GitLab 9.1.
> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/10467) for merge requests, award emoji, notes, and abuse reports in GitLab 9.1.
> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/235765) in GitLab 13.5.
> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/235765) in GitLab 13.5.
> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/342327) in GitLab 14.5. Default prefix added.
> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/342327) in GitLab 14.5. Default prefix added.
Project access tokens are similar to [personal access tokens](../../profile/personal_access_tokens.md)
You can use a project access token to authenticate:
except they are attached to a project rather than a user. They can be used to:
- Authenticate with the [GitLab API](../../../api/index.md#personalproject-access-tokens).
- With the [GitLab API](../../../api/index.md#personalproject-access-tokens).
- Authenticate with Git using HTTP Basic Authentication. If you are asked for a username when
- With Git, when using HTTP Basic Authentication.
authenticating, you can use any non-empty value because only the token is needed.
Project access tokens:
After you configure a project access token, you don't need a password when you authenticate.
Instead, you can enter any non-blank value.
- Expire on the date you define, at midnight UTC.
Project access tokens are similar to [personal access tokens](../../profile/personal_access_tokens.md),
- Are supported for self-managed instances on Free tier and above. Free self-managed instances
except they are associated with a project rather than a user.
should:
- Review their security and compliance policies with regards to
You can use project access tokens:
- On GitLab SaaS if you have the Premium license tier or higher. Personal 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
- Consider [disabling project access tokens](#enable-or-disable-project-access-token-creation) to
- Consider [disabling project access tokens](#enable-or-disable-project-access-token-creation) to
lower potential abuse.
lower potential abuse.
- Are also supported on GitLab SaaS Premium and above (excluding [trial licenses](https://about.gitlab.com/free-trial/).)
For examples of how you can use a project access token to authenticate with the API, see the
[relevant section from our API Docs](../../../api/index.md#personalproject-access-tokens).
NOTE:
For GitLab.com and self-managed instances, the default prefix is `glpat-`.
## Creating a project access token
1. Log in to GitLab.
1. Navigate to the project you would like to create an access token for.
1. In the **Settings** menu choose **Access Tokens**.
1. Choose a name and optional expiry date for the token.
1. Choose a role for the token.
1. Choose the [desired scopes](#limiting-scopes-of-a-project-access-token).
1. Click the **Create project access token** button.
1. 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](https://gitlab.com/gitlab-org/gitlab/-/issues/210181) in GitLab 13.0.
> - [Excluded from license seat use](https://gitlab.com/gitlab-org/gitlab/-/issues/223695) in GitLab 13.5.
Project bot users are [GitLab-created service accounts](../../../subscriptions/self_managed/index.md#billable-users) and do not count as licensed seats.
For each project access token created, a bot user is created and added to the project with
## Create a project access token
the [specified level permissions](../../permissions.md#project-members-permissions).
For the bot:
To create a project access token:
- 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 access 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.
1. On the top bar, select **Menu > Projects** and find your project.
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-project-access-token).
1. Select **Create project access token**.
These bot users are included in a project's **Project information > Members** list but cannot be modified. Also, a bot
A project access token is displayed. Save the project access token somewhere safe. After you leave or refresh the page, you can't view it again.
user cannot be added to any other project.
When the project access token is [revoked](#revoking-a-project-access-token), the bot user is deleted
## Revoke a project access token
and all records are moved to a system-wide user with the username "Ghost User". For more
information, see [Associated Records](../../profile/account/delete_account.md#associated-records).
## Revoking a project access token
To revoke a project access token:
At any time, you can revoke any project access token by clicking the
1. On the top bar, select **Menu > Projects** and find your project.
respective **Revoke** button in **Settings > Access Tokens**.
1. On the left sidebar, select **Settings > Access Tokens**.
1. Next to the project access token to revoke, select **Revoke**.
## Limiting scopes of a project access token
## Scopes for a project access token
Project access tokens can be created with one or more scopes that allow various
The scope determines the actions you can perform when you authenticate with a project access token.
actions that a given token can perform. The available scopes are depicted in
| `api` | Grants complete read/write access to the scoped project API, including the [Package Registry](../../packages/package_registry/index.md). |
| `api` | Grants complete read and write access to the scoped project API, including the [Package Registry](../../packages/package_registry/index.md). |
| `read_api` | Grants read access to the scoped project API, including the [Package Registry](../../packages/package_registry/index.md). |
| `read_api` | Grants read access to the scoped project API, including the [Package Registry](../../packages/package_registry/index.md). |
| `read_registry` | Allows read-access (pull) to [container registry](../../packages/container_registry/index.md) images if a project is private and authorization is required. |
| `read_registry` | Allows read access (pull) to the [Container Registry](../../packages/container_registry/index.md) images if a project is private and authorization is required. |
| `write_registry` | Allows write-access (push) to [container registry](../../packages/container_registry/index.md). |
| `write_registry` | Allows write access (push) to the [Container Registry](../../packages/container_registry/index.md). |
| `read_repository` | Allows read-only access (pull) to the repository. |
| `read_repository` | Allows read access (pull) to the repository. |
| `write_repository` | Allows read-write access (pull, push) to the repository. |
| `write_repository` | Allows read and write access (pull and push) to the repository. |
## Enable or disable project access token creation
## Enable or disable project access token creation
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/287707) in GitLab 13.11.
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/287707) 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**.
To enable or disable project access token creation for all projects in a top-level group:
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)**
1. On the top bar, select **Menu > Groups** and find your group.
1. On the left sidebar, select **Settings > General**.
1. Expand **Permissions, LFS, 2FA**.
1. Under **Permissions**, turn on or off **Allow project access token creation**.
NOTE:
Even when creation is disabled, you can still use and revoke existing project access tokens.
This section describes a workaround and is subject to change.
## Group access tokens **(FREE SELF)**
Group access tokens let you use a single token to:
With group access tokens, you can use a single token to:
- Perform actions at the group level.
- Perform actions for groups.
- Manage the projects within the group.
- Manage the projects within the group.
- In [GitLab 14.2](https://gitlab.com/gitlab-org/gitlab/-/issues/330718) and later, authenticate
- In [GitLab 14.2](https://gitlab.com/gitlab-org/gitlab/-/issues/330718) and later, authenticate with Git over HTTPS.
with Git over HTTPS.
We don't support group access tokens in the GitLab UI, though GitLab self-managed
NOTE:
administrators can create them using the [Rails console](../../../administration/operations/rails_console.md).
You cannot use the UI to create a group access token. [An issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/214045)
to add this functionality. This section describes a workaround.
If you are an administrator of a self-managed GitLab instance, you can create a group access token in the
For a demo of the group access token workaround, see <ahref="https://www.youtube.com/watch?v=W2fg1P1xmU0">Demo: Group Level Access Tokens</a>.
For a demo of the group access token workaround, see <ahref="https://www.youtube.com/watch?v=W2fg1P1xmU0">Demo: Group Level Access Tokens</a>.
...
@@ -127,37 +104,71 @@ administrators can create them using the [Rails console](../../../administration
...
@@ -127,37 +104,71 @@ administrators can create them using the [Rails console](../../../administration
### Create a group access token
### Create a group access token
To create a group access token, run the following in a Rails console:
To create a group access token:
```ruby
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. Run the following commands in a [Rails console](../../../administration/operations/rails_console.md):
1. Pass the group access token in the `PRIVATE-TOKEN` header to GitLab REST APIs. For example:
```ruby
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
```
-[Create an epic](../../../api/epics.md#new-epic) on the group.
1. Test if the generated group access token works:
-[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)
1. Use the group access token in the `PRIVATE-TOKEN` header with GitLab REST APIs. For example:
using HTTPS.
-[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
### Revoke a group access token
To revoke a group access token, run the following in a Rails console:
To revoke a group access token, run the following command in a [Rails console](../../../administration/operations/rails_console.md):
```ruby
```ruby
bot=User.find_by(username: 'group_109_bot')# the owner of the token you want to revoke
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=bot.personal_access_tokens.last# the token you want to revoke
token.revoke!
token.revoke!
```
```
## Project bot users
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210181) in GitLab 13.0.
> - [Excluded from license seat use](https://gitlab.com/gitlab-org/gitlab/-/issues/223695) in GitLab 13.5.
Project bot users are [GitLab-created service accounts](../../../subscriptions/self_managed/index.md#billable-users).
Each time you create a project access token, a bot user is created and added to the project.
These bot users do not count as licensed seats.
The bot users have [permissions](../../permissions.md#project-members-permissions) that correspond with the
selected role and [scope](#scopes-for-a-project-access-token) of the project access token.
- The name is set to the name of the token.
- The username is set to `project_{project_id}_bot` for the first access token. For example, `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 access 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.
Bot users:
- Are included in a project's member list but cannot be modified.
- Cannot be added to any other project.
When the project access token is [revoked](#revoke-a-project-access-token):
- The bot user is deleted.
- All records are moved to a system-wide user with the username `Ghost User`. For more information, see
