Add the ways needed to authenticate to the registry via CI/CD

3 files changed, 32 insertions, 22 deletions

diff --git a/doc/user/profile/personal_access_tokens.md b/doc/user/profile/personal_access_tokens.md
index 25d6c34409c..7d55048c994 100644
--- a/doc/user/profile/personal_access_tokens.md
+++ b/doc/user/profile/personal_access_tokens.md
@@ -45,16 +45,14 @@ the following table.
 | Scope | Description |
 | ----- | ----------- |
 |`read_user` | Allows access to the read-only endpoints under `/users`. Essentially, any of the `GET` requests in the [Users API][users] are allowed ([introduced][ce-5951] in GitLab 8.15). |
-| `api` | Grants complete access to the API (read/write) ([introduced][ce-5951] in GitLab 8.15). Required for accessing Git repositories over HTTP when 2FA is enabled. |
-| `read_registry` | Allows to read [container registry] images if a project is private and authorization is required ([introduced][ce-11845] in GitLab 9.3). |
+| `api` | Grants complete access to the API and Container Registry (read/write) ([introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5951) in GitLab 8.15). Required for accessing Git repositories over HTTP when 2FA is enabled. |
+| `read_registry` | Allows to read (pull) [container registry] images if a project is private and authorization is required ([introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/11845) in GitLab 9.3). |
 | `sudo` | Allows performing API actions as any user in the system (if the authenticated user is an admin) ([introduced][ce-14838] in GitLab 10.2). |
-| `read_repository` | Allows read-access to the repository through git clone. |
+| `read_repository` | Allows read-access (pull) to the repository through git clone. |
 
 [2fa]: ../account/two_factor_authentication.md
 [api]: ../../api/README.md
 [ce-3749]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/3749
-[ce-5951]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5951
-[ce-11845]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/11845
 [ce-14838]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/14838
 [container registry]: ../project/container_registry.md
 [users]: ../../api/users.md
diff --git a/doc/user/project/container_registry.md b/doc/user/project/container_registry.md
index 2709ebb6f05..1b1827a2658 100644
--- a/doc/user/project/container_registry.md
+++ b/doc/user/project/container_registry.md
@@ -119,12 +119,17 @@ and [Using the GitLab Container Registry documentation](../../ci/docker/using_do
 > Project Deploy Tokens were [introduced][ce-17894] in GitLab 10.7
 
 If a project is private, credentials will need to be provided for authorization.
-The preferred way to do this, is either by using a [personal access tokens][pat] or a [project deploy token][pdt].
+There are two ways to do this:
+
+- By using a [personal access token](../profile/personal_access_tokens.md).
+- By using a [deploy token](../project/deploy_tokens/index.md).
+
 The minimal scope needed for both of them is `read_registry`.
 
-Example of using a personal access token:
-```
-docker login registry.example.com -u <your_username> -p <your_access_token>
+Example of using a token:
+
+```sh
+docker login registry.example.com -u <username> -p <token>
 ```
 
 ## Troubleshooting the GitLab Container Registry
diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md
index ff647b2f0a2..dc73194309c 100644
--- a/doc/user/project/deploy_tokens/index.md
+++ b/doc/user/project/deploy_tokens/index.md
@@ -9,7 +9,7 @@ at midnight UTC and that they can be only managed by [maintainers](https://docs.
 
 ## Creating a Deploy Token
 
-You can create as many deploy tokens as you like from the settings of your project: 
+You can create as many deploy tokens as you like from the settings of your project:
 
 1. Log in to your GitLab account.
 1. Go to the project you want to create Deploy Tokens for.
@@ -49,14 +49,13 @@ To download a repository using a Deploy Token, you just need to:
 2. Take note of your `username` and `token`
 3. `git clone` the project using the Deploy Token:
 
+    ```sh
+    git clone http://<username>:<deploy_token>@gitlab.example.com/tanuki/awesome_project.git
+    ```
 
-```bash
-git clone https://<username>:<deploy_token>@gitlab.example.com/tanuki/awesome_project.git
-```
-
-Just replace `<username>` and `<deploy_token>` with the proper values
+Replace `<username>` and `<deploy_token>` with the proper values.
 
-### Read container registry images
+### Read Container Registry images
 
 To read the container registry images, you'll need to:
 
@@ -64,21 +63,29 @@ To read the container registry images, you'll need to:
 2. Take note of your `username` and `token`
 3. Log in to GitLab’s Container Registry using the deploy token:
 
-```
+```sh
 docker login registry.example.com -u <username> -p <deploy_token>
 ```
 
-Just replace `<username>` and `<deploy_token>` with the proper values. Then you can simply 
+Just replace `<username>` and `<deploy_token>` with the proper values. Then you can simply
 pull images from your Container Registry.
 
 ### GitLab Deploy Token
 
 > [Introduced][ce-18414] in GitLab 10.8.
 
-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.
+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. With the GitLab Deploy Token, the
+`read_registry` scope is implied.
+
+After you create the token, you can login to the Container Registry using
+those variables:
+
+```sh
+docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY
+```
 
 [ce-17894]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/17894
 [ce-11845]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/11845