diff options
Diffstat (limited to 'doc/user/project/deploy_tokens/index.md')
| -rw-r--r-- | doc/user/project/deploy_tokens/index.md | 69 |
1 files changed, 39 insertions, 30 deletions
diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index 5ca421dda5b..1ac528ca4ae 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -13,57 +13,61 @@ type: howto > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29280) from **Settings > CI / CD** in GitLab 12.10.1. > - [Added package registry scopes](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) 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 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](../../permissions.md). -If you have a key pair, you might want to use [deploy keys](../../../ssh/README.md#deploy-keys) instead. +If you have a key pair, you might want to use [deploy keys](../../../ssh/README.md#deploy-keys) +instead. ## Creating a Deploy Token -You can create as many deploy tokens as you like from the settings of your project. Alternatively, you can also create [group-scoped deploy tokens](#group-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](#group-deploy-token). -1. Log in to your GitLab account. +1. Sign in to your GitLab account. 1. Go to the project (or group) you want to create Deploy Tokens for. 1. Go to **Settings > Repository**. 1. Click on "Expand" on **Deploy Tokens** section. 1. Choose a name, expiry date (optional), and username (optional) for the token. 1. Choose the [desired scopes](#limiting-scopes-of-a-deploy-token). -1. Click on **Create deploy token**. -1. Save the deploy token somewhere safe. Once you leave or refresh +1. Select **Create deploy token**. +1. Save the deploy token somewhere safe. After you leave or refresh the page, **you won't be able to access it again**.  ## Deploy token expiration -Deploy tokens expire on the date you define, at midnight UTC. +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. +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. +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](../../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 | +| 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 | | `write_package_registry` | Allows write access to the package registry. | 13.0 | ## Deploy token custom username > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/29639) in GitLab 12.1. -The default username format is `gitlab+deploy-token-#{n}`. Some tools or platforms may not support this format, -in such case you can specify custom username to be used when creating the deploy token. +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 @@ -87,13 +91,13 @@ To read the container registry images, you'll need to: 1. Create a Deploy Token with `read_registry` as a scope. 1. Take note of your `username` and `token`. -1. Log in to GitLab’s Container Registry using the deploy token: +1. Sign in to GitLab’s Container Registry using the deploy token: ```shell docker login -u <username> -p <deploy_token> registry.example.com ``` -Just replace `<username>` and `<deploy_token>` with the proper values. Then you can simply +Replace `<username>` and `<deploy_token>` with the proper values. You can now pull images from your Container Registry. ### Push Container Registry images @@ -104,13 +108,13 @@ 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`. -1. Log in to GitLab’s Container Registry using the deploy token: +1. Sign in to GitLab’s Container Registry using the deploy token: ```shell docker login -u <username> -p <deploy_token> registry.example.com ``` -Just replace `<username>` and `<deploy_token>` with the proper values. Then you can simply +Replace `<username>` and `<deploy_token>` with the proper values. You can now push images to your Container Registry. ### Read or pull packages @@ -121,7 +125,8 @@ 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`. -1. For the [package type of your choice](./../../packages/index.md), follow the authentication instructions for deploy tokens. +1. For the [package type of your choice](../../packages/index.md), follow the + authentication instructions for deploy tokens. ### Push or upload packages @@ -131,7 +136,8 @@ 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`. -1. For the [package type of your choice](./../../packages/index.md), follow the authentication instructions for deploy tokens. +1. For the [package type of your choice](../../packages/index.md), follow the + authentication instructions for deploy tokens. ### Group Deploy Token @@ -158,10 +164,10 @@ apply consistently when cloning the repository of related projects. 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 -automatically exposed to the CI/CD jobs as environment variables: `CI_DEPLOY_USER` and -`CI_DEPLOY_PASSWORD`, respectively. +automatically exposed to the CI/CD jobs as environment variables: `CI_DEPLOY_USER` +and `CI_DEPLOY_PASSWORD`, respectively. -After you create the token, you can login to the Container Registry using +After you create the token, you can sign in to the Container Registry by using those variables: ```shell @@ -169,4 +175,7 @@ docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY ``` NOTE: **Note:** -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. See [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/214014) for details. +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). |