Merge branch 'docs/docker-build' into 'master'

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

Closes gitlab-com/support-forum#3825

See merge request gitlab-org/gitlab-ce!21538

1 files changed, 61 insertions, 23 deletions

diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md
index 0b64c8caba7..3b41036cd14 100644
--- a/doc/ci/docker/using_docker_build.md
+++ b/doc/ci/docker/using_docker_build.md
@@ -395,8 +395,67 @@ 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` 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` fetches
+  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. However, it's still possible to have a
+  stale image if you re-build a given commit after a dependency has changed.
+- You don't want to build directly to `latest` tag in case there are multiple jobs
+  happening simultaneously.
+
+### Authenticating to the Container Registry
+
+There are three ways to authenticate to the Container Registry via GitLab CI/CD
+and depend on the visibility of your project.
+
+For all projects, mostly suitable for public ones:
+
+- **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 automatically
+  set with the `$CI_JOB_TOKEN` variable. This allows you to automate building and deploying
+  your Docker images and has read/write access to the Registry. This is ephemeral,
+  so it's only valid for one job. You can use the following example as-is:
+
+    ```sh
+    docker login -u gitlab-ci-token -p $CI_JOB_TOKEN $CI_REGISTRY
+    ```
+
+For private and internal projects:
+
+- **Using a personal access token**: You can create and use a
+  [personal access token](../../user/profile/personal_access_tokens.md)
+  in case your project is private:
+    - For read (pull) access, the scope should be `read_registry`.
+    - For read/write (pull/push) access, use `api`.
+  Replace the `<username>` and `<access_token>` in the following example:
+
+    ```sh
+    docker login -u <username> -p <access_token> $CI_REGISTRY
+    ```
+
+- **Using the GitLab Deploy Token**: You can create and use a
+  [special deploy token](../../user/project/deploy_tokens/index.md#gitlab-deploy-token)
+  with your private projects. It provides read-only (pull) access to the Registry.
+  Once created, you can use the special environment variables, and GitLab CI/CD
+  will fill them in for you. You can use the following example as-is:
+
+    ```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
@@ -414,11 +473,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
@@ -508,22 +562,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