- Creating a Deploy token
- Deploy token expiration
- Revoking a deploy token
- Limiting scopes of a deploy token
- Deploy token custom username
- Usage
- Git clone a repository
- Read Container Registry images
- Push Container Registry images
- Read or pull packages
- Push or upload packages
- Group deploy token
- GitLab deploy token
Version history
- Introduced in GitLab 10.7.
- Moved from Settings > Repository in GitLab 12.9.
- Added
write_registryscope in GitLab 12.10. - Moved from Settings > CI/CD in GitLab 12.10.1.
- Added package registry scopes in GitLab 13.0.
Deploy tokens allow you to download (git clone) or push and pull packages andcontainer registry images of a project without having a user and a password.
Deploy tokens can be managed by maintainers only.
Deploy tokens cannot be used with the GitLab API.
If you have a key pair, you might want to use deploy keysinstead.
Creating a Deploy token
You can create as many deploy tokens as you need from the settings of yourproject. Alternatively, you can also create group-scoped deploy tokens.
- Sign in to your GitLab account.
- Go to the project (or group) you want to create deploy tokens for.
- Go to Settings > Repository.
- Expand the Deploy tokens section.
- Choose a name, expiry date (optional), and username (optional) for the token.
- Choose the desired scopes.
- Select Create deploy token.
- Save the deploy token somewhere safe. After you leave or refreshthe page, you can’t access it again.
Deploy token expiration
Deploy tokens expire at midnight UTC on the date you define.
Revoking a deploy token
To revoke a deploy token, under the Active deploy tokens area,select the respective Revoke button.
Limiting scopes of a deploy token
Deploy tokens can be created with different scopes that allow various actionsthat a given token can perform. The available scopes are depicted in thefollowing table along with GitLab version it was introduced in:
| Scope | Description | Introduced in GitLab Version |
|---|---|---|
read_repository | Allows read-access to the repository through git clone | 10.7 |
read_registry | Allows read-access to container registry images if a project is private and authorization is required. | 10.7 |
write_registry | Allows write-access (push) to container registry. | 12.10 |
read_package_registry | Allows read access to the package registry. | 13.0 |
write_package_registry | Allows write access to the package registry. | 13.0 |
Deploy token custom username
Introduced in GitLab 12.1.
The default username format is gitlab+deploy-token-{n}. Some tools orplatforms may not support this format; in this case you can specify a customusername to be used when creating the deploy token.
Usage
Git clone a repository
To download a repository using a deploy token:
- Create a deploy token with
read_repositoryas a scope. - Take note of your
usernameandtoken. git clonethe project using the deploy token:git clone https://<username>:<deploy_token>@gitlab.example.com/tanuki/awesome_project.git
Replace <username> and <deploy_token> with the proper values.
Read Container Registry images
To read the container registry images, you must:
- Create a deploy token with
read_registryas a scope. - Take note of your
usernameandtoken. - Sign in to the GitLab Container Registry using the deploy token:
docker login -u <username> -p <deploy_token> registry.example.comReplace <username> and <deploy_token> with the proper values. You can nowpull images from your Container Registry.
Push Container Registry images
Introduced in GitLab 12.10.
To push the container registry images, you must:
- Create a deploy token with
write_registryas a scope. - Take note of your
usernameandtoken. Sign in to the GitLab Container Registry using the deploy token:
docker login -u <username> -p <deploy_token> registry.example.com
Replace <username> and <deploy_token> with the proper values. You can nowpush images to your Container Registry.
Read or pull packages
Introduced in GitLab 13.0.
To pull packages in the GitLab package registry, you must:
- Create a deploy token with
read_package_registryas a scope. - Take note of your
usernameandtoken. - For the package type of your choice, follow theauthentication instructions for deploy tokens.
Example request publishing a NuGet package using a deploy token:
nuget source Add -Name GitLab -Source "https://gitlab.example.com/api/v4/projects/10/packages/nuget/index.json" -UserName deploy-token-username -Password 12345678asdfnuget push mypkg.nupkg -Source GitLabPush or upload packages
Introduced in GitLab 13.0.
To upload packages in the GitLab package registry, you must:
- Create a deploy token with
write_package_registryas a scope. - Take note of your
usernameandtoken. - For the package type of your choice, follow theauthentication instructions for deploy tokens.
Group deploy token
Introduced in GitLab 12.9.
A deploy token created at the group level can be used across all projects thatbelong either to the specific group or to one of its subgroups.
For an overview, see Group Deploy Tokens.
The Group deploy tokens UI is now accessible under Settings > Repository,not Settings > CI/CD as indicated in the video.
To use a group deploy token:
- Create a deploy token for a group.
- Use it the same way you use a project deploy token whencloning a repository.
The scopes applied to a group deploy token (such as read_repository)apply consistently when cloning the repository of related projects.
GitLab deploy token
Introduced in GitLab 10.8.
There’s a special case when it comes to deploy tokens. If a user creates onenamed gitlab-deploy-token, the username and token of the deploy token isautomatically exposed to the CI/CD jobs as CI/CD variables: CI_DEPLOY_USERand CI_DEPLOY_PASSWORD, respectively.
After you create the token, you can sign in to the Container Registry by usingthose variables:
docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRYThe special handling for the gitlab-deploy-token deploy token is notimplemented for group deploy tokens. To make the group-level deploy token available forCI/CD jobs, the CI_DEPLOY_USER and CI_DEPLOY_PASSWORD variables should be set under Settings to the name and token of the group deploy token respectively.
