• Scope
• GitLab deploy token
  • 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

Deploy tokens

Added package registry scopes in GitLab 13.0.

You can use a deploy token to enable authentication of deployment tasks, independent of a user account. In most cases you use a deploy token from an external host, like a build server or CI/CD server.

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 is gitlab+deploy-token-{n}. You can specify a custom username when you create the deploy token.
• token: password in the HTTP authentication framework.

You can use a deploy token for HTTP authentication to 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 create it. Expiry occurs at midnight UTC on that date.

Scope

A deploy token’s scope determines the actions it can perform.

GitLab deploy token

A GitLab deploy token is a special type of deploy token. If you create a deploy token named gitlab-deploy-token, the deploy token is automatically exposed to the CI/CD jobs as variables, for use in a CI/CD pipeline:

• CI_DEPLOY_USER: Username
• CI_DEPLOY_PASSWORD: Token

For example, to use a GitLab token to log in to your GitLab container registry:

docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY

GitLab public API

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 more information, see Authenticate with the registry.

Create a deploy token

Create a deploy token to automate deployment tasks that can run independently of a user account.

Prerequisites:

• You must have at least the Maintainer role for the project or group.

1. On the top bar, select Main menu, and:
   • For a project deploy token, select Projects and find your project.
   • For a group deploy token, select Groups and find your group.
2. On the left sidebar, select Settings > Repository.
3. Expand Deploy tokens.
4. Complete the fields, and select the desired scopes.
5. Select Create deploy token.

Record the deploy token’s values. After you leave or refresh the page, you cannot access it again.

Revoke a deploy token

Revoke a token when it’s no longer required.

Prerequisites:

• You must have at least the Maintainer role for the project or group.

To revoke a deploy token:

1. On the top bar, select Main menu, and:
   • For a project deploy token, select Projects and find your project.
   • For a group deploy token, select Groups and find your group.
2. On the left sidebar, select Settings > Repository.
3. Expand Deploy tokens.
4. 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:

docker login -u <username> -p <deploy_token> registry.example.com
docker 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 write_registry scope.

Example of using a deploy token to push an image to a container registry:

docker login -u <username> -p <deploy_token> registry.example.com
docker 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 authentication instructions 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 authentication instructions 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 and write_registry scopes.

Follow the dependency proxy authentication instructions.