debian-mirror-gitlab/doc/user/project/deploy_tokens/index.md

stage	group	info	type
Release	Release	To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments	howto

Deploy Tokens

• Introduced in GitLab 10.7.
• Moved from Settings > Repository in GitLab 12.9.
• Added write_registry scope 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 and container 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 keys instead.

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.

1. Sign in to your GitLab account.
2. Go to the project (or group) you want to create Deploy Tokens for.
3. Go to Settings > Repository.
4. Click on "Expand" on Deploy Tokens section.
5. Choose a name, expiry date (optional), and username (optional) for the token.
6. Choose the desired scopes.
7. Select Create deploy token.
8. 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

At any time, you can revoke any deploy token by just clicking the respective Revoke button under the 'Active deploy tokens' area.

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	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 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, you just need to:

1. Create a Deploy Token with read_repository as a scope.

2. Take note of your username and token.

3. 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:

1. Create a Deploy Token with read_registry as a scope.
2. Take note of your username and token.
3. 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:

1. Create a Deploy Token with write_registry as a scope.

2. Take note of your username and token.

3. 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:

1. Create a Deploy Token with read_package_registry as a scope.
2. Take note of your username and token.
3. For the package type of your choice, follow the authentication instructions for deploy tokens.

Example request publishing a generic package using a deploy token:

curl --header "DEPLOY-TOKEN: <deploy_token>" \
     --upload-file path/to/file.txt \
     "https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/0.0.1/file.txt?status=hidden"

Example response:

{
  "message":"201 Created"
}

Push or upload packages

Introduced in GitLab 13.0.

To upload packages in the GitLab package registry, you must:

1. Create a Deploy Token with write_package_registry as a scope.
2. Take note of your username and token.
3. 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:

1. Create a deploy token for a group.
2. 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.

GitLab Deploy Token

Introduced in GitLab 10.8.

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: The special handling for the gitlab-deploy-token deploy token is not implemented for group deploy tokens. To make the group-level deploy token available for CI/CD jobs, use the workaround in issue 214014.