1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
|
---
stage: Release
group: Release
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
---
# Deploy tokens **(FREE)**
> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/199370) from **Settings > Repository** to **Settings > CI/CD** in GitLab 12.9.
> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/22743) `write_registry` scope in GitLab 12.10.
> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29280) from **Settings > CI/CD** to **Settings > Repository** in GitLab 12.10.1.
> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication)
to the following endpoints:
- GitLab Package Registry public API.
- [Git commands](https://git-scm.com/docs/gitcredentials#_description).
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.
Deploy tokens can't be used for Git operations and Package Registry operations if [external authorization](../../admin_area/settings/external_authorization.md) 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](../../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. |
## GitLab deploy token
> - 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.
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:
```shell
docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY
```
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.
### 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](../../packages/package_registry/index.md#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.
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**.
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.
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**.
## 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:
```shell
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:
```shell
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:
```shell
docker login -u <username> -p <deploy_token> registry.example.com
docker push $CONTAINER_TEST_IMAGE
```
## Pull packages from a package registry
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) in GitLab 13.0.
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](../../packages/index.md), follow the authentication
instructions for deploy tokens.
Example of installing a NuGet package from a GitLab registry:
```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
```
## Push packages to a package repository
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) in GitLab 13.0.
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](../../packages/index.md), follow the authentication
instructions for deploy tokens.
Example of publishing a NuGet package to a package registry:
```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 push mypkg.nupkg -Source GitLab
```
## 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).
## Troubleshooting
### Error: `api error: Repository or object not found:`
When using a group deploy token to clone from LFS objects, you might get `404 Not Found` responses
and this error message. This occurs because of a bug, documented in
[issue 235398](https://gitlab.com/gitlab-org/gitlab/-/issues/235398).
```plaintext
api error: Repository or object not found:
https://<URL-with-token>.git/info/lfs/objects/batch
Check that it exists and that you have proper access to it
```
The workaround is to use a project deploy token.
|
