Merge branch 'russell/ctrt-deploy-tokens-part2' into 'master'

Edit deploy token tasks to adhere to CTRT convention

See merge request !100378



Merged-by: Russell Dickenson <rdickenson@gitlab.com>
Co-authored-by: Jon Glassman <jglassman@gitlab.com>

doc/user/packages/dependency_proxy/index.md

@@ -84,7 +84,7 @@ You can authenticate using:
 
 - Your GitLab username and password.
 - A [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `read_registry` and `write_registry`.
-- A [group deploy token](../../../user/project/deploy_tokens/index.md#group-deploy-token) with the scope set to `read_registry` and `write_registry`.
+- A [group deploy token](../../../user/project/deploy_tokens/index.md) with the scope set to `read_registry` and `write_registry`.
 
 Users accessing the Dependency Proxy with a personal access token or username and password must
 have at least the Guest role for the group they pull images from.

doc/user/packages/package_registry/index.md

@@ -53,7 +53,7 @@ For most package types, the following credential types are valid:
 - [Project deploy token](../../project/deploy_tokens/index.md):
   allows access to all packages in a project. Good for granting and revoking project access to many
   users.
-- [Group deploy token](../../project/deploy_tokens/index.md#group-deploy-token):
+- [Group deploy token](../../project/deploy_tokens/index.md):
   allows access to all packages in a group and its subgroups. Good for granting and revoking access
   to a large number of packages to sets of users.
 - [Job token](../../../ci/jobs/ci_job_token.md):

doc/user/project/deploy_tokens/index.md

@@ -83,158 +83,150 @@ Deploy tokens can't be used with the GitLab public API. However, you can use dep
 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).
 
-## Creating a Deploy token
+## Create a 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).
+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. Sign in to your GitLab account.
 1. On the top bar, select **Main menu**, and:
-   - For a project, select ***Projects** and find your project.
-   - For a group, select **Groups** and find your group.
+   - 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. Choose a name, and optionally, an expiration date and username for the token.
-1. Choose the [desired scopes](#scope).
+1. Complete the fields, and select the desired [scopes](#scope).
 1. Select **Create deploy token**.
 
-Save the deploy token somewhere safe. After you leave or refresh
-the page, **you can't access it again**.
+Record the deploy token's values. After you leave or refresh the page, **you cannot access it
+again**.
+
+## Revoke a deploy token
 
-![Personal access tokens page](img/deploy_tokens_ui.png)
+Revoke a token when it's no longer required.
 
-## Revoking a deploy token
+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, select ***Projects** and find your project.
-   - For a group, select **Groups** and find your group.
+   - 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**.
 
-## Usage
+## Clone a repository
+
+You can use a deploy token to clone a repository.
+
+Prerequisites:
 
-### Git clone a repository
+- A deploy token with the `read_repository` scope.
 
-To download a repository using a deploy token:
+Example of using a deploy token to clone a repository:
 
-1. Create a deploy token with `read_repository` as a scope.
-1. Take note of your `username` and `token`.
-1. `git clone` the project using the deploy token:
+```shell
+git clone https://<username>:<deploy_token>@gitlab.example.com/tanuki/awesome_project.git
+```
 
-   ```shell
-   git clone https://<username>:<deploy_token>@gitlab.example.com/tanuki/awesome_project.git
-   ```
+## Pull images from a container registry
 
-Replace `<username>` and `<deploy_token>` with the proper values.
+You can use a deploy token to pull images from a container registry.
 
-### Read Container Registry images
+Prerequisites:
 
-To read the container registry images, you must:
+- A deploy token with the `read_registry` scope.
 
-1. Create a deploy token with `read_registry` as a scope.
-1. Take note of your `username` and `token`.
-1. Sign in to the GitLab Container Registry using the deploy token:
+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
 ```
 
-Replace `<username>` and `<deploy_token>` with the proper values. You can now
-pull images from your Container Registry.
-
-### Push Container Registry images
+## Push images to a container registry
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22743) in GitLab 12.10.
+You can use a deploy token to push images to a container registry.
 
-To push the container registry images, you must:
+Prerequisites:
 
-1. Create a deploy token with `write_registry` as a scope.
-1. Take note of your `username` and `token`.
-1. Sign in to the GitLab Container Registry using the deploy token:
+- A deploy token with the `write_registry` scope.
 
-   ```shell
-   docker login -u <username> -p <deploy_token> registry.example.com
-   ```
+Example of using a deploy token to push an image to a container registry:
 
-Replace `<username>` and `<deploy_token>` with the proper values. You can now
-push images to your Container Registry.
+```shell
+docker login -u <username> -p <deploy_token> registry.example.com
+docker push $CONTAINER_TEST_IMAGE
+```
 
-### Read or pull packages
+## Pull packages from a package registry
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) in GitLab 13.0.
 
-To pull packages in the GitLab package registry, you must:
+You can use a deploy token to pull packages from a package registry.
 
-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.
+Prerequisites:
 
-Example request publishing a NuGet package using a deploy token:
+- A deploy token with the `read_package_registry` scope.
 
-```shell
-nuget source Add -Name GitLab -Source "https://gitlab.example.com/api/v4/projects/10/packages/nuget/index.json" -UserName deploy-token-username -Password 12345678asdf
+For the [package type of your choice](../../packages/index.md), follow the authentication
+instructions for deploy tokens.
 
-nuget push mypkg.nupkg -Source GitLab
+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 or upload packages
+## Push packages to a package repository
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) in GitLab 13.0.
 
-To upload packages in the GitLab package registry, you must:
-
-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.
-
-### Group deploy token
+You can use a deploy token to push packages to a GitLab package registry.
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21765) in GitLab 12.9.
+Prerequisites:
 
-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.
+- A deploy token with the `write_package_registry` scope.
 
-<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
-For an overview, see [Group Deploy Tokens](https://youtu.be/8kxTJvaD9ks).
+For the [package type of your choice](../../packages/index.md), follow the authentication
+instructions for deploy tokens.
 
-The Group deploy tokens UI is now accessible under **Settings > Repository**,
-not **Settings > CI/CD** as indicated in the video.
+Example of publishing a NuGet package to a package registry:
 
-To use a group deploy token:
+```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
+```
 
-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).
+## Pull images from the dependency proxy
 
-The scopes applied to a group deploy token (such as `read_repository`)
-apply consistently when cloning the repository of related projects.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/280586) in GitLab 14.2.
 
-### Pull images from the Dependency Proxy
+You can use a deploy token to pull images from the dependency proxy.
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/280586) in GitLab 14.2.
+Prerequisites:
 
-To pull images from the Dependency Proxy, you must:
+- A deploy token with `read_registry` and `write_registry` scopes.
 
-1. Create a group deploy token with both `read_registry` and `write_registry` scopes.
-1. Take note of your `username` and `token`.
-1. Follow the Dependency Proxy [authentication instructions](../../packages/dependency_proxy/index.md).
+Follow the dependency proxy [authentication instructions](../../packages/dependency_proxy/index.md).
 
 ## Troubleshooting
 
-### Group deploy tokens and LFS
+### Error: `api error: Repository or object not found:`
 
-A bug
-[prevents Group Deploy Tokens from cloning LFS objects](https://gitlab.com/gitlab-org/gitlab/-/issues/235398).
-If you receive `404 Not Found` errors and this error,
-use a Project Deploy Token to work around the bug:
+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.