232 lines
8.9 KiB
Markdown
232 lines
8.9 KiB
Markdown
---
|
|
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.
|
|
|
|
## 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.
|