2020-06-23 00:09:42 +05:30
---
stage: Release
2021-02-22 17:27:13 +05:30
group: Release
2022-11-25 23:54:43 +05:30
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
2020-06-23 00:09:42 +05:30
---
2022-03-02 08:16:31 +05:30
# Deploy tokens **(FREE)**
2018-05-09 12:01:36 +05:30
2023-04-23 21:23:45 +05:30
> [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) package registry scopes in GitLab 13.0.
2018-05-09 12:01:36 +05:30
2022-11-25 23:54:43 +05:30
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.
2018-05-09 12:01:36 +05:30
2022-11-25 23:54:43 +05:30
With a deploy token, automated tasks can:
2020-04-08 14:13:33 +05:30
2022-11-25 23:54:43 +05:30
- Clone Git repositories.
- Pull from and push to a GitLab container registry.
- Pull from and push to a GitLab package registry.
2021-02-22 17:27:13 +05:30
2022-11-25 23:54:43 +05:30
A deploy token is a pair of values:
2021-10-27 15:23:28 +05:30
2022-11-25 23:54:43 +05:30
- **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.
2018-05-09 12:01:36 +05:30
2022-11-25 23:54:43 +05:30
You can use a deploy token for [HTTP authentication ](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication )
to the following endpoints:
2018-05-09 12:01:36 +05:30
2022-11-25 23:54:43 +05:30
- GitLab Package Registry public API.
- [Git commands ](https://git-scm.com/docs/gitcredentials#_description ).
2018-05-09 12:01:36 +05:30
2022-11-25 23:54:43 +05:30
You can create deploy tokens at either the project or group level:
2021-12-11 22:18:48 +05:30
2022-11-25 23:54:43 +05:30
- **Project deploy token**: Permissions apply only to the project.
- **Group deploy token**: Permissions apply to all projects in the group.
2018-05-09 12:01:36 +05:30
2022-11-25 23:54:43 +05:30
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.
2018-05-09 12:01:36 +05:30
2023-04-23 21:23:45 +05:30
WARNING:
You cannot use new or existing deploy tokens for Git operations and Package Registry operations if
[external authorization ](../../admin_area/settings/external_authorization.md ) is enabled.
2023-01-10 11:22:00 +05:30
2022-11-25 23:54:43 +05:30
## Scope
2020-04-08 14:13:33 +05:30
2022-11-25 23:54:43 +05:30
A deploy token's scope determines the actions it can perform.
2020-04-08 14:13:33 +05:30
2022-11-25 23:54:43 +05:30
| 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 ](../../packages/container_registry/index.md ). |
| `write_registry` | Write access (push) to the project's [container registry ](../../packages/container_registry/index.md ). |
| `read_package_registry` | Read-only access to the project's package registry. |
| `write_package_registry` | Write access to the project's package registry. |
2018-05-09 12:01:36 +05:30
2022-11-25 23:54:43 +05:30
## GitLab deploy token
2021-12-11 22:18:48 +05:30
2022-11-25 23:54:43 +05:30
> - Support for `gitlab-deploy-token` at the group level [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214014) in GitLab 15.1 [with a flag](../../../administration/feature_flags.md) named `ci_variable_for_group_gitlab_deploy_token`. Enabled by default.
> - [Feature flag `ci_variable_for_group_gitlab_deploy_token`](https://gitlab.com/gitlab-org/gitlab/-/issues/363621) removed in GitLab 15.4.
2018-05-09 12:01:36 +05:30
2022-11-25 23:54:43 +05:30
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:
2018-05-09 12:01:36 +05:30
2022-11-25 23:54:43 +05:30
- `CI_DEPLOY_USER` : Username
- `CI_DEPLOY_PASSWORD` : Token
2018-05-09 12:01:36 +05:30
2022-11-25 23:54:43 +05:30
For example, to use a GitLab token to log in to your GitLab container registry:
2018-05-09 12:01:36 +05:30
2022-11-25 23:54:43 +05:30
```shell
docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY
```
2019-09-30 21:07:59 +05:30
2022-11-25 23:54:43 +05:30
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 a group deploy token available for CI/CD jobs, set the
`CI_DEPLOY_USER` and `CI_DEPLOY_PASSWORD` CI/CD variables in **Settings > CI/CD > Variables** to the
name and token of the group deploy token.
2019-09-30 21:07:59 +05:30
2022-11-25 23:54:43 +05:30
### GitLab public API
2019-09-30 21:07:59 +05:30
2022-11-25 23:54:43 +05:30
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 ](../../packages/package_registry/index.md#authenticate-with-the-registry ).
2018-05-09 12:01:36 +05:30
2022-11-25 23:54:43 +05:30
## Create a deploy token
2018-05-09 12:01:36 +05:30
2022-11-25 23:54:43 +05:30
Create a deploy token to automate deployment tasks that can run independently of a user account.
2018-05-09 12:01:36 +05:30
2022-11-25 23:54:43 +05:30
Prerequisites:
2018-05-09 12:01:36 +05:30
2022-11-25 23:54:43 +05:30
- You must have at least the Maintainer role for the project or group.
2018-05-09 12:01:36 +05:30
2022-11-25 23:54:43 +05:30
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.
1. On the left sidebar, select **Settings > Repository** .
1. Expand **Deploy tokens** .
1. Complete the fields, and select the desired [scopes ](#scope ).
1. Select **Create deploy token** .
2018-05-09 12:01:36 +05:30
2022-11-25 23:54:43 +05:30
Record the deploy token's values. After you leave or refresh the page, **you cannot access it
again**.
2018-05-09 12:01:36 +05:30
2022-11-25 23:54:43 +05:30
## Revoke a deploy token
2018-05-09 12:01:36 +05:30
2022-11-25 23:54:43 +05:30
Revoke a token when it's no longer required.
2018-05-09 12:01:36 +05:30
2022-11-25 23:54:43 +05:30
Prerequisites:
2018-05-09 12:01:36 +05:30
2022-11-25 23:54:43 +05:30
- You must have at least the Maintainer role for the project or group.
2018-05-09 12:01:36 +05:30
2022-11-25 23:54:43 +05:30
To revoke a deploy token:
2020-04-22 19:07:51 +05:30
2022-11-25 23:54:43 +05:30
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.
1. On the left sidebar, select **Settings > Repository** .
1. Expand **Deploy tokens** .
1. In the **Active Deploy Tokens** section, by the token you want to revoke, select **Revoke** .
2020-07-28 23:09:34 +05:30
2022-11-25 23:54:43 +05:30
## Clone a repository
2020-04-22 19:07:51 +05:30
2022-11-25 23:54:43 +05:30
You can use a deploy token to clone a repository.
2020-04-22 19:07:51 +05:30
2022-11-25 23:54:43 +05:30
Prerequisites:
2020-04-22 19:07:51 +05:30
2022-11-25 23:54:43 +05:30
- A deploy token with the `read_repository` scope.
2020-04-22 19:07:51 +05:30
2022-11-25 23:54:43 +05:30
Example of using a deploy token to clone a repository:
2020-05-24 23:13:21 +05:30
2022-11-25 23:54:43 +05:30
```shell
git clone https://< username > :< deploy_token > @gitlab.example.com/tanuki/awesome_project.git
```
2020-07-28 23:09:34 +05:30
2022-11-25 23:54:43 +05:30
## Pull images from a container registry
2020-05-24 23:13:21 +05:30
2022-11-25 23:54:43 +05:30
You can use a deploy token to pull images from a container registry.
2020-05-24 23:13:21 +05:30
2022-11-25 23:54:43 +05:30
Prerequisites:
2021-04-17 20:07:23 +05:30
2022-11-25 23:54:43 +05:30
- A deploy token with the `read_registry` scope.
2021-04-17 20:07:23 +05:30
2022-11-25 23:54:43 +05:30
Example of using a deploy token to pull images from a container registry:
```shell
docker login -u < username > -p < deploy_token > registry.example.com
docker pull $CONTAINER_TEST_IMAGE
2021-04-17 20:07:23 +05:30
```
2022-11-25 23:54:43 +05:30
## Push images to a container registry
2020-05-24 23:13:21 +05:30
2022-11-25 23:54:43 +05:30
You can use a deploy token to push images to a container registry.
2020-07-28 23:09:34 +05:30
2022-11-25 23:54:43 +05:30
Prerequisites:
2020-05-24 23:13:21 +05:30
2022-11-25 23:54:43 +05:30
- A deploy token with the `write_registry` scope.
2020-05-24 23:13:21 +05:30
2022-11-25 23:54:43 +05:30
Example of using a deploy token to push an image to a container registry:
2020-04-08 14:13:33 +05:30
2022-11-25 23:54:43 +05:30
```shell
docker login -u < username > -p < deploy_token > registry.example.com
docker push $CONTAINER_TEST_IMAGE
```
2020-04-08 14:13:33 +05:30
2022-11-25 23:54:43 +05:30
## Pull packages from a package registry
2020-04-08 14:13:33 +05:30
2022-11-25 23:54:43 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) in GitLab 13.0.
2020-05-24 23:13:21 +05:30
2022-11-25 23:54:43 +05:30
You can use a deploy token to pull packages from a package registry.
2021-02-22 17:27:13 +05:30
2022-11-25 23:54:43 +05:30
Prerequisites:
2020-04-08 14:13:33 +05:30
2022-11-25 23:54:43 +05:30
- A deploy token with the `read_package_registry` scope.
2020-04-08 14:13:33 +05:30
2022-11-25 23:54:43 +05:30
For the [package type of your choice ](../../packages/index.md ), follow the authentication
instructions for deploy tokens.
2020-04-08 14:13:33 +05:30
2022-11-25 23:54:43 +05:30
Example of installing a NuGet package from a GitLab registry:
2021-10-27 15:23:28 +05:30
2022-11-25 23:54:43 +05:30
```shell
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
```
2021-10-27 15:23:28 +05:30
2023-04-23 21:23:45 +05:30
## Push packages to a package registry
2021-10-27 15:23:28 +05:30
2022-11-25 23:54:43 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) in GitLab 13.0.
2021-10-27 15:23:28 +05:30
2022-11-25 23:54:43 +05:30
You can use a deploy token to push packages to a GitLab package registry.
2018-10-15 14:42:47 +05:30
2022-11-25 23:54:43 +05:30
Prerequisites:
- A deploy token with the `write_package_registry` scope.
2022-07-23 23:45:48 +05:30
2022-11-25 23:54:43 +05:30
For the [package type of your choice ](../../packages/index.md ), follow the authentication
instructions for deploy tokens.
2018-12-13 13:39:08 +05:30
2022-11-25 23:54:43 +05:30
Example of publishing a NuGet package to a package registry:
2018-12-13 13:39:08 +05:30
2020-03-13 15:44:24 +05:30
```shell
2022-11-25 23:54:43 +05:30
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
2018-12-13 13:39:08 +05:30
```
2020-05-24 23:13:21 +05:30
2022-11-25 23:54:43 +05:30
## Pull images from the dependency proxy
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/280586) in GitLab 14.2.
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 ](../../packages/dependency_proxy/index.md ).