2020-05-29 14:08:26 -04:00
---
stage: Release
group: Progressive Delivery
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
type: howto
---
2018-04-06 04:57:33 -04:00
# Deploy Tokens
2018-03-31 20:11:28 -04:00
2020-03-30 23:07:51 -04:00
> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17894) in GitLab 10.7.
2020-05-21 23:08:28 -04:00
> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/199370) from **Settings > Repository** in GitLab 12.9.
2020-04-13 20:09:57 -04:00
> - [Added `write_registry` scope](https://gitlab.com/gitlab-org/gitlab/-/issues/22743) in GitLab 12.10.
2020-04-28 23:09:39 -04:00
> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29280) from **Settings > CI / CD** in GitLab 12.10.1.
2020-06-18 14:08:58 -04:00
> - [Added package registry scopes](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) in GitLab 13.0.
2018-03-31 20:11:28 -04:00
2020-11-09 19:08:52 -05:00
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.
2018-03-31 20:11:28 -04:00
2020-03-12 02:09:35 -04:00
Deploy tokens can be managed by [maintainers only ](../../permissions.md ).
2020-11-09 19:08:52 -05:00
If you have a key pair, you might want to use [deploy keys ](../../../ssh/README.md#deploy-keys )
instead.
2018-03-31 20:11:28 -04:00
2018-04-05 21:04:11 -04:00
## Creating a Deploy Token
2018-03-31 20:11:28 -04:00
2020-11-09 19:08:52 -05:00
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 ](#group-deploy-token ).
2018-03-31 20:11:28 -04:00
2020-11-09 19:08:52 -05:00
1. Sign in to your GitLab account.
2020-03-01 19:07:41 -05:00
1. Go to the project (or group) you want to create Deploy Tokens for.
2020-07-28 23:09:51 -04:00
1. Go to **Settings > Repository** .
2018-11-12 19:39:21 -05:00
1. Click on "Expand" on **Deploy Tokens** section.
2019-07-01 11:49:05 -04:00
1. Choose a name, expiry date (optional), and username (optional) for the token.
2018-03-31 20:11:28 -04:00
1. Choose the [desired scopes ](#limiting-scopes-of-a-deploy-token ).
2020-11-09 19:08:52 -05:00
1. Select **Create deploy token** .
1. Save the deploy token somewhere safe. After you leave or refresh
2018-03-31 20:11:28 -04:00
the page, **you won't be able to access it again** .
![Personal access tokens page ](img/deploy_tokens.png )
2020-03-12 02:09:35 -04:00
## Deploy token expiration
2020-11-09 19:08:52 -05:00
Deploy tokens expire at midnight UTC on the date you define.
2020-03-12 02:09:35 -04:00
2018-04-23 00:15:10 -04:00
## Revoking a deploy token
2018-03-31 20:11:28 -04:00
2020-11-09 19:08:52 -05:00
At any time, you can revoke any deploy token by just clicking the respective
**Revoke** button under the 'Active deploy tokens' area.
2018-03-31 20:11:28 -04:00
## Limiting scopes of a deploy token
2020-11-09 19:08:52 -05:00
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:
2018-03-31 20:11:28 -04:00
2020-11-09 19:08:52 -05:00
| 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 ](../../packages/container_registry/index.md ) images if a project is private and authorization is required. | 10.7 |
| `write_registry` | Allows write-access (push) to [container registry ](../../packages/container_registry/index.md ). | 12.10 |
| `read_package_registry` | Allows read access to the package registry. | 13.0 |
2020-06-18 14:08:58 -04:00
| `write_package_registry` | Allows write access to the package registry. | 13.0 |
2018-03-31 20:11:28 -04:00
2019-07-01 11:49:05 -04:00
## Deploy token custom username
2020-02-06 10:09:11 -05:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/29639) in GitLab 12.1.
2019-07-01 11:49:05 -04:00
2020-11-09 19:08:52 -05:00
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.
2019-07-01 11:49:05 -04:00
2018-03-31 20:11:28 -04:00
## Usage
### Git clone a repository
To download a repository using a Deploy Token, you just need to:
2018-04-04 19:43:41 -04:00
1. Create a Deploy Token with `read_repository` as a scope.
2018-11-12 19:39:21 -05:00
1. Take note of your `username` and `token` .
1. `git clone` the project using the Deploy Token:
2018-03-31 20:11:28 -04:00
2020-01-30 10:09:15 -05:00
```shell
2020-04-21 11:21:10 -04:00
git clone https://< username > :< deploy_token > @gitlab.example.com/tanuki/awesome_project.git
2019-07-14 23:02:30 -04:00
```
2018-03-31 20:11:28 -04:00
2018-09-05 06:57:43 -04:00
Replace `<username>` and `<deploy_token>` with the proper values.
2018-03-31 20:11:28 -04:00
2018-09-05 06:57:43 -04:00
### Read Container Registry images
2018-03-31 20:11:28 -04:00
To read the container registry images, you'll need to:
1. Create a Deploy Token with `read_registry` as a scope.
2018-11-12 19:39:21 -05:00
1. Take note of your `username` and `token` .
2020-11-09 19:08:52 -05:00
1. Sign in to GitLab’ s Container Registry using the deploy token:
2018-03-31 20:11:28 -04:00
2020-01-30 10:09:15 -05:00
```shell
2019-10-11 02:06:27 -04:00
docker login -u < username > -p < deploy_token > registry.example.com
2018-03-31 20:11:28 -04:00
```
2018-04-05 23:02:13 -04:00
2020-11-09 19:08:52 -05:00
Replace `<username>` and `<deploy_token>` with the proper values. You can now
2018-04-05 23:02:13 -04:00
pull images from your Container Registry.
2018-03-31 20:11:28 -04:00
2020-04-13 20:09:57 -04:00
### Push Container Registry images
2020-06-18 14:08:58 -04:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22743) in GitLab 12.10.
2020-04-13 20:09:57 -04:00
To push the container registry images, you'll need to:
1. Create a Deploy Token with `write_registry` as a scope.
1. Take note of your `username` and `token` .
2020-11-09 19:08:52 -05:00
1. Sign in to GitLab’ s Container Registry using the deploy token:
2020-04-13 20:09:57 -04:00
```shell
docker login -u < username > -p < deploy_token > registry.example.com
```
2020-11-09 19:08:52 -05:00
Replace `<username>` and `<deploy_token>` with the proper values. You can now
2020-04-13 20:09:57 -04:00
push images to your Container Registry.
2020-05-13 23:07:52 -04:00
### Read or pull packages
2020-06-18 14:08:58 -04:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) in GitLab 13.0.
2020-05-13 23:07:52 -04:00
To pull packages in the GitLab package registry, you'll need to:
1. Create a Deploy Token with `read_package_registry` as a scope.
1. Take note of your `username` and `token` .
2020-11-09 19:08:52 -05:00
1. For the [package type of your choice ](../../packages/index.md ), follow the
authentication instructions for deploy tokens.
2020-05-13 23:07:52 -04:00
### Push or upload packages
2020-06-18 14:08:58 -04:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) in GitLab 13.0.
2020-05-13 23:07:52 -04:00
To upload packages in the GitLab package registry, you'll need to:
1. Create a Deploy Token with `write_package_registry` as a scope.
1. Take note of your `username` and `token` .
2020-11-09 19:08:52 -05:00
1. For the [package type of your choice ](../../packages/index.md ), follow the
authentication instructions for deploy tokens.
2020-05-13 23:07:52 -04:00
2020-03-01 19:07:41 -05:00
### Group Deploy Token
2020-05-21 23:08:28 -04:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21765) in GitLab 12.9.
2020-03-01 19:07:41 -05:00
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.
2020-04-23 20:09:28 -04:00
< i class = "fa fa-youtube-play youtube" aria-hidden = "true" > < / i >
For an overview, see [Group Deploy Tokens ](https://youtu.be/8kxTJvaD9ks ).
2020-03-01 19:07:41 -05:00
To use a group deploy token:
1. [Create ](#creating-a-deploy-token ) a deploy token for a group.
1. Use it the same way you use a project deploy token when
[cloning a repository ](#git-clone-a-repository ).
The scopes applied to a group deploy token (such as `read_repository` ) will
apply consistently when cloning the repository of related projects.
2018-04-16 17:18:43 -04:00
### GitLab Deploy Token
2020-03-30 23:07:51 -04:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18414) in GitLab 10.8.
2018-04-16 17:18:43 -04:00
2018-09-05 06:57:43 -04:00
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 will be
2020-11-09 19:08:52 -05:00
automatically exposed to the CI/CD jobs as environment variables: `CI_DEPLOY_USER`
and `CI_DEPLOY_PASSWORD` , respectively.
2018-09-05 06:57:43 -04:00
2020-11-09 19:08:52 -05:00
After you create the token, you can sign in to the Container Registry by using
2018-09-05 06:57:43 -04:00
those variables:
2020-01-30 10:09:15 -05:00
```shell
2018-09-05 06:57:43 -04:00
docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY
```
2020-04-24 20:10:07 -04:00
NOTE: **Note:**
2020-11-09 19:08:52 -05:00
The special handling for the `gitlab-deploy-token` deploy token is not currently
implemented for group deploy tokens. For the deploy token to be available for
CI/CD jobs, it must be created at the project level. For details, see
[this issue ](https://gitlab.com/gitlab-org/gitlab/-/issues/214014 ).