Add the ways needed to authenticate to the registry via CI/CDdocs/docker-build

3 files changed, 71 insertions, 37 deletions

diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md
index 63338ff632c..7238c11dc47 100644
--- a/doc/ci/docker/using_docker_build.md
+++ b/doc/ci/docker/using_docker_build.md
@@ -394,8 +394,56 @@ If you're running multiple Runners you will have to modify all configuration fil
   login to GitLab's Container Registry.
 
 Once you've built a Docker image, you can push it up to the built-in
-[GitLab Container Registry](../../user/project/container_registry.md). For example,
-if you're using docker-in-docker on your runners, this is how your `.gitlab-ci.yml`
+[GitLab Container Registry](../../user/project/container_registry.md).
+Some things you should be aware of:
+
+- You must [log in to the container registry](#authenticating-to-the-container-registry)
+  before running commands. You can do this in the `before_script` if multiple
+  jobs depend on it.
+- Using `docker build --pull` makes sure that Docker fetches any changes to base
+  images before building just in case your cache is stale. It takes slightly
+  longer, but means you don’t get stuck without security patches to base images.
+- Doing an explicit `docker pull` before each `docker run` makes sure to fetch
+  the latest image that was just built. This is especially important if you are
+  using multiple runners that cache images locally. Using the git SHA in your
+  image tag makes this less necessary since each job will be unique and you
+  shouldn't ever have a stale image, but it's still possible if you re-build a
+  given commit after a dependency has changed.
+- You don't want to build directly to `latest` in case there are multiple jobs
+  happening simultaneously.
+
+### Authenticating to the Container Registry
+
+There are 3 ways to authenticate to the Container Registry:
+
+- **Using the special `gitlab-ci-token` user**: This user is created for you in order to
+  push to the Registry connected to your project. Its password is provided in the
+  `$CI_JOB_TOKEN` variable. This allows you to automate building and deployment
+  of your Docker images and has read and write access to the registry.
+  This is ephemeral, so it's only valid for one job:
+
+    ```sh
+    docker login -u gitlab-ci-token -p $CI_JOB_TOKEN $CI_REGISTRY
+    ```
+
+- **Using a personal access token**: A [personal access token](../../user/profile/personal_access_tokens.md)
+  can be used in case your project is private. For read access, the scope
+  should be `read_registry`. For read/write access, use `api`:
+
+    ```sh
+    docker login -u <username> -p <access_token> $CI_REGISTRY
+    ```
+
+- **Using a deploy token**: A special [deploy token](../../user/project/deploy_tokens/index.md#gitlab-deploy-token)
+  can be used for usage with private projects. It provides read-only access:
+
+    ```sh
+    docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY
+    ```
+
+### Container Registry examples
+
+If you're using docker-in-docker on your Runners, this is how your `.gitlab-ci.yml`
 could look like:
 
 ```yaml
@@ -413,11 +461,6 @@ could look like:
      - docker push registry.example.com/group/project/image:latest
 ```
 
-You have to use the special `gitlab-ci-token` user created for you in order to
-push to the Registry connected to your project. Its password is provided in the
-`$CI_JOB_TOKEN` variable. This allows you to automate building and deployment
-of your Docker images.
-
 You can also make use of [other variables](../variables/README.md) to avoid hardcoding:
 
 ```yaml
@@ -507,22 +550,6 @@ deploy:
     - master
 ```
 
-Some things you should be aware of when using the Container Registry:
-
-- You must log in to the container registry before running commands. Putting
-  this in `before_script` will run it before each job.
-- Using `docker build --pull` makes sure that Docker fetches any changes to base
-  images before building just in case your cache is stale. It takes slightly
-  longer, but means you don’t get stuck without security patches to base images.
-- Doing an explicit `docker pull` before each `docker run` makes sure to fetch
-  the latest image that was just built. This is especially important if you are
-  using multiple runners that cache images locally. Using the git SHA in your
-  image tag makes this less necessary since each job will be unique and you
-  shouldn't ever have a stale image, but it's still possible if you re-build a
-  given commit after a dependency has changed.
-- You don't want to build directly to `latest` in case there are multiple jobs
-  happening simultaneously.
-
 [docker-in-docker]: https://blog.docker.com/2013/09/docker-can-now-run-within-docker/
 [docker-cap]: https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities
 [2fa]: ../../user/profile/account/two_factor_authentication.md
diff --git a/doc/user/project/container_registry.md b/doc/user/project/container_registry.md
index 03302b3815d..b916413ad92 100644
--- a/doc/user/project/container_registry.md
+++ b/doc/user/project/container_registry.md
@@ -27,7 +27,7 @@ to enable it.
 1. First, ask your system administrator to enable GitLab Container Registry
    following the [administration documentation](../../administration/container_registry.md).
    If you are using GitLab.com, this is enabled by default so you can start using
-   the Registry immediately. Currently there is a soft (10GB) size restriction for 
+   the Registry immediately. Currently there is a soft (10GB) size restriction for
    registry on GitLab.com, as part of the [repository size limit](repository/index.html#repository-size).
 1. Go to your [project's General settings](settings/index.md#sharing-and-permissions)
    and enable the **Container Registry** feature on your project. For new
@@ -119,12 +119,15 @@ 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].
+The preferred way to do this, is either by using a
+[personal access token](../profile/personal_access_tokens.md) or 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
@@ -291,6 +294,4 @@ Once the right permissions were set, the error will go away.
 [ce-11845]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/11845
 [ce-17894]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/17894
 [docker-docs]: https://docs.docker.com/engine/userguide/intro/
-[pat]: ../profile/personal_access_tokens.md
-[pdt]: ../project/deploy_tokens/index.md
-[reconfigure]: ../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure
\ No newline at end of file
+[reconfigure]: ../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure
diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md
index 0b9b49f326f..a17ee3bcc40 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.
@@ -50,7 +50,7 @@ To download a repository using a Deploy Token, you just need to:
 3. `git clone` the project using the Deploy Token:
 
 
-```bash
+```sh
 git clone http://<username>:<deploy_token>@gitlab.example.com/tanuki/awesome_project.git
 ```
 
@@ -64,11 +64,11 @@ 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
@@ -76,10 +76,16 @@ pull images from your Container Registry.
 > [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 
+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.
 
+In that case, you can use 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
 [ce-18414]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/18414