Deploy tokens (FREE)
Deploy tokens allow you to download (git clone
) or push and pull packages and
container registry images of a project without having a user and a password.
Deploy tokens can be managed only by users with the Maintainer role.
Deploy tokens can't be used with the GitLab public API. However, you can use deploy tokens with some endpoints, such as those from the Package Registry. For details, see Authenticate with the registry.
Deploy tokens are tied to the project and stay enabled even when the user who created the token is removed from the project.
If you have a key pair, you might want to use deploy keys instead.
Deploy tokens can't be used for Git operations and Package Registry operations if external authorization is enabled.
Creating a Deploy token
You can create as many deploy tokens as you need from the settings of your project. Alternatively, you can also create group-scoped deploy tokens.
- Sign in to your GitLab account.
- On the top bar, select Main menu > Projects or Main menu > Groups to find your project or group.
- On the left sidebar, select Settings > Repository.
- Expand Deploy tokens.
- Choose a name, and optionally, an expiration date and username for the token.
- Choose the desired scopes.
- Select Create deploy token.
Save the deploy token somewhere safe. After you leave or refresh the 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:
- On the top bar, select Main menu > Projects or Main menu > Groups to find your project or group.
- On the left sidebar, select Settings > Repository.
- Expand Deploy tokens.
- In the Active Deploy Tokens section, by the token you want to revoke, select Revoke.
Limiting scopes of a deploy token
Deploy tokens can be created with different scopes that allow various actions that a given token can perform. The available scopes are depicted in the following 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
|
-- |
read_registry |
Allows read-access to container registry images if a project is private and authorization is required. | -- |
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 or
platforms may not support this format; in this case you can specify a custom
username 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_repository
as a scope. -
Take note of your
username
andtoken
. -
git clone
the 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_registry
as a scope. - Take note of your
username
andtoken
. - 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 now
pull 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_registry
as a scope. -
Take note of your
username
andtoken
. -
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 now
push 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_registry
as a scope. - Take note of your
username
andtoken
. - For the package type of your choice, follow the authentication 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 12345678asdf
nuget push mypkg.nupkg -Source GitLab
Push 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_registry
as a scope. - Take note of your
username
andtoken
. - For the package type of your choice, follow the authentication 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 that belong 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 when cloning a repository.
The scopes applied to a group deploy token (such as read_repository
)
apply consistently when cloning the repository of related projects.
Pull images from the Dependency Proxy
Introduced in GitLab 14.2.
To pull images from the Dependency Proxy, you must:
- Create a group deploy token with both
read_registry
andwrite_registry
scopes. - Take note of your
username
andtoken
. - Follow the Dependency Proxy authentication instructions.
GitLab deploy token
- Support for
gitlab-deploy-token
at the group level introduced in GitLab 15.1 with a flag namedci_variable_for_group_gitlab_deploy_token
. Enabled by default.- Feature flag
ci_variable_for_group_gitlab_deploy_token
removed in GitLab 15.4.
There's a special case when it comes to deploy tokens. If a user creates one
named gitlab-deploy-token
, the username and token of the deploy token is
automatically exposed to the CI/CD jobs as CI/CD variables: CI_DEPLOY_USER
and CI_DEPLOY_PASSWORD
, respectively.
After you create the token, you can sign in to the Container Registry by using those variables:
docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY
NOTE:
In GitLab 15.0 and earlier, the special handling for the gitlab-deploy-token
deploy token
does not work for group deploy tokens. To make the group-level deploy token available
for CI/CD jobs, the CI_DEPLOY_USER
and CI_DEPLOY_PASSWORD
CI/CD variables must be
set in Settings > CI/CD > Variables to the name and token of the group deploy token.
Troubleshooting
Group deploy tokens and LFS
A bug
prevents Group Deploy Tokens from cloning LFS objects.
If you receive 404 Not Found
errors and this error,
use a Project Deploy Token to work around the bug:
api error: Repository or object not found:
https://<URL-with-token>.git/info/lfs/objects/batch
Check that it exists and that you have proper access to it