Personal access tokens
You can also use personal access tokens with Git to authenticate over HTTP or SSH. Personal access tokens are required when Two-Factor Authentication (2FA) is enabled. In both cases, you can authenticate with a token in place of your password.
Personal access tokens expire on the date you define, at midnight UTC.
- GitLab runs a check at 01:00 AM UTC every day to identify personal access tokens that will expire in under seven days. The owners of these tokens are notified by email.
- In GitLab Ultimate, administrators may limit the lifetime of personal access tokens.
For examples of how you can use a personal access token to authenticate with the API, see the following section from our API Docs.
GitLab also offers impersonation tokens which are created by administrators via the API. They're a great fit for automated authentication as a specific user.
Creating a personal access token
You can create as many personal access tokens as you like from your GitLab profile.
- Log in to GitLab.
- In the upper-right corner, click your avatar and select Settings.
- On the User Settings menu, select Access Tokens.
- Choose a name and optional expiry date for the token.
- Choose the desired scopes.
- Click the Create personal access token button.
- Save the personal access token somewhere safe. Once you leave or refresh the page, you won't be able to access it again.
Revoking a personal access token
At any time, you can revoke any personal access token by clicking the respective Revoke button under the Active Personal Access Token area.
Limiting scopes of a personal access token
Personal 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.
||GitLab 8.15||Allows access to the read-only endpoints under
||GitLab 8.15||Grants complete read/write access to the API, including all groups and projects, the container registry, and the package registry.|
||GitLab 12.10||Grants read access to the API, including all groups and projects, the container registry, and the package registry.|
||GitLab 9.3||Allows to read (pull) container registry images if a project is private and authorization is required.|
||GitLab 10.2||Allows performing API actions as any user in the system (if the authenticated user is an admin).|
||GitLab 10.7||Allows read-only access (pull) to the repository through
||GitLab 11.11||Allows read-write access (pull, push) to the repository through
Programmatically creating a personal access token
You can programmatically create a predetermined personal access token for use in automation or tests. You will need sufficient access to run a Rails console session for your GitLab instance.
To create a token belonging to a user with username
automation-bot, run the
following in the Rails console (
sudo gitlab-rails console):
user = User.find_by_username('automation-bot') token = user.personal_access_tokens.create(scopes: [:read_user, :read_repository], name: 'Automation token') token.set_token('token-string-here123') token.save!
This can be shortened into a single-line shell command using the GitLab Rails Runner:
sudo gitlab-rails runner "token = User.find_by_username('automation-bot').personal_access_tokens.create(scopes: [:read_user, :read_repository], name: 'Automation token'); token.set_token('token-string-here123'); token.save!"
NOTE: Note: The token string must be 20 characters in length, or it will not be recognized as a personal access token.
The list of valid scopes and what they do can be found in the source code.
Programmatically revoking a personal access token
You can programmatically revoke a personal access token. You will need sufficient access to run a Rails console session for your GitLab instance.
To revoke a known token
token-string-here123, run the following in the Rails
sudo gitlab-rails console):
token = PersonalAccessToken.find_by_token('token-string-here123') token.revoke!
This can be shorted into a single-line shell command using the GitLab Rails Runner:
sudo gitlab-rails runner "PersonalAccessToken.find_by_token('token-string-here123').revoke!"