- Scope
- GitLab deploy token
- GitLab deploy token security
- GitLab public API
- Create a deploy token
- Revoke a deploy token
- Clone a repository
- Pull images from a container registry
- Push images to a container registry
- Pull packages from a package registry
- Push packages to a package registry
- Pull images from the dependency proxy
Tier: Free, Premium, UltimateOffering: GitLab.com, Self-managed, GitLab Dedicated
You can use a deploy token to enable authentication of deployment tasks, independent of a useraccount. In most cases you use a deploy token from an external host, like a build server or CI/CDserver.
With a deploy token, automated tasks can:
- Clone Git repositories.
- Pull from and push to a GitLab container registry.
- Pull from and push to a GitLab package registry.
A deploy token is a pair of values:
- username:
username
in the HTTP authentication framework. The default username format isgitlab+deploy-token-{n}
. You can specify a custom username when you create the deploy token. - token:
password
in the HTTP authentication framework.
Deploy tokens do not support SSH authentication.
You can use a deploy token for HTTP authenticationto the following endpoints:
- GitLab package registry public API.
- Git commands.
You can create deploy tokens at either the project or group level:
- Project deploy token: Permissions apply only to the project.
- Group deploy token: Permissions apply to all projects in the group.
By default, a deploy token does not expire. You can optionally set an expiry date when you createit. Expiry occurs at midnight UTC on that date.
You cannot use new or existing deploy tokens for Git operations and package registry operations ifexternal authorization is enabled.
Scope
A deploy token’s scope determines the actions it can perform.
Scope | Description |
---|---|
read_repository | Read-only access to the repository using git clone . |
read_registry | Read-only access to the images in the project’s container registry. |
write_registry | Write access (push) to the project’s container registry. You need both read and write access to push images. |
read_package_registry | Read-only access to the project’s package registry. |
write_package_registry | Write access to the project’s package registry. |
GitLab deploy token
History
- 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.
A GitLab deploy token is a special type of deploy token. If you create a deploy token namedgitlab-deploy-token
, the deploy token is automatically exposed to the CI/CD jobs as variables, foruse in a CI/CD pipeline:
CI_DEPLOY_USER
: UsernameCI_DEPLOY_PASSWORD
: Token
For example, to use a GitLab token to sign in to your GitLab container registry:
echo "$CI_DEPLOY_PASSWORD" | docker login $CI_REGISTRY -u $CI_DEPLOY_USER --password-stdin
In GitLab 15.0 and earlier, the special handling for the gitlab-deploy-token
deploy token does notwork for group deploy tokens. To make a group deploy token available for CI/CD jobs, set theCI_DEPLOY_USER
and CI_DEPLOY_PASSWORD
CI/CD variables in Settings > CI/CD > Variables to thename and token of the group deploy token.
GitLab deploy token security
GitLab deploy tokens are long-lived, making them attractive for attackers.
To prevent leaking the deploy token, you should also configure yourrunners to be secure:
- Avoid using Docker
privileged
mode if the machines are re-used. - Avoid using the shell executor when jobsrun on the same machine.
An insecure GitLab Runner configuration increases the risk that someone can steal tokens from otherjobs.
GitLab public API
Deploy tokens can’t be used with the GitLab public API. However, you can use deploy tokens with someendpoints, such as those from the package registry. You can tell an endpoint belongs to the package registry because the URL has the string packages/<format>
. For example: https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/0.0.1/file.txt
. For more information, seeAuthenticate with the registry.
Create a deploy token
Create a deploy token to automate deployment tasks that can run independently of a user account.
Prerequisites:
- To create a group deploy token, you must have the Owner role for the group.
- To create a project deploy token, you must have at least the Maintainer role for the project.
- On the left sidebar, select Search or go to and find your project or group.
- Select Settings > Repository.
- Expand Deploy tokens.
- Select Add token.
- Complete the fields, and select the desired scopes.
- Select Create deploy token.
Record the deploy token’s values. After you leave or refresh the page, you cannot access itagain.
Revoke a deploy token
Revoke a token when it’s no longer required.
Prerequisites:
- To revoke a group deploy token, you must have the Owner role for the group.
- To revoke a project deploy token, you must have at least the Maintainer role for the project.
To revoke a deploy token:
- On the left sidebar, select Search or go to and find your project or group.
- Select Settings > Repository.
- Expand Deploy tokens.
- In the Active Deploy Tokens section, by the token you want to revoke, select Revoke.
Clone a repository
You can use a deploy token to clone a repository.
Prerequisites:
- A deploy token with the
read_repository
scope.
Example of using a deploy token to clone a repository:
git clone https://<username>:<deploy_token>@gitlab.example.com/tanuki/awesome_project.git
Pull images from a container registry
You can use a deploy token to pull images from a container registry.
Prerequisites:
- A deploy token with the
read_registry
scope.
Example of using a deploy token to pull images from a container registry:
echo "$DEPLOY_TOKEN" | docker login -u <username> --password-stdin registry.example.comdocker pull $CONTAINER_TEST_IMAGE
Push images to a container registry
You can use a deploy token to push images to a container registry.
Prerequisites:
- A deploy token with the
read_registry
andwrite_registry
scope.
Example of using a deploy token to push an image to a container registry:
echo "$DEPLOY_TOKEN" | docker login -u <username> --password-stdin registry.example.comdocker push $CONTAINER_TEST_IMAGE
Pull packages from a package registry
You can use a deploy token to pull packages from a package registry.
Prerequisites:
- A deploy token with the
read_package_registry
scope.
For the package type of your choice, follow the authenticationinstructions for deploy tokens.
Example of installing a NuGet package from a GitLab registry:
nuget source Add -Name GitLab -Source "https://gitlab.example.com/api/v4/projects/10/packages/nuget/index.json" -UserName <username> -Password <deploy_token>nuget install mypkg.nupkg
Push packages to a package registry
You can use a deploy token to push packages to a GitLab package registry.
Prerequisites:
- A deploy token with the
write_package_registry
scope.
For the package type of your choice, follow the authenticationinstructions for deploy tokens.
Example of publishing a NuGet package to a package registry:
nuget source Add -Name GitLab -Source "https://gitlab.example.com/api/v4/projects/10/packages/nuget/index.json" -UserName <username> -Password <deploy_token>nuget push mypkg.nupkg -Source GitLab
Pull images from the dependency proxy
You can use a deploy token to pull images from the dependency proxy.
Prerequisites:
- A deploy token with
read_registry
andwrite_registry
scopes.
Follow the dependency proxy authentication instructions.